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Texas Instruments (Tl) reserves the right to make changes to or to discontinue 
any semiconductor product or service identified in this publication without notice. 
Tl advises its customers to obtain the latest version of the relevant information 
to verify, before placing orders, that the information being relied upon is current. 


Tl warrants performance of its semiconductor products to current specifications 
in accordance with TI’s standard warranty. Testing and other quality control tech- 
niques are utilized to the extent Tl deems necessary to support this warranty. Un- 
less mandated by government requirements, specific testing of all parameters of 
each device is not necessarily performed. 


Tl assumes no liability for T] applications assistance, customer product design, 
software performance, or infringement of patents or services described herein. 
_ Nordoes T1| warrant or represent that license, either express or implied, is granted 
under any patent right, copyright, mask work right, or other intellectual property 
right of Tl covering or relating to any combination, machine, or process in which 
such semiconductor products or services might be or are used. 
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PC-DOS is a trademark of International Business Machines. 
VAX and VMS are trademarks of Digital Equipment Corporation. 
UNIX is a trademark of American Telephone and Telegraph. 
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Preface 


Read This First 


This preface summarizes the chapters, lists related documentation, and de- 
scribes the style and symbol conventions used in this book. 


How to Use This Manual 


Chapter 1 


Chapter 2 


Chapter 3 


Chapter 4 


Chapter 5 


This document contains the following chapters: 


Introduction and Installation 
Provides an overview of the TMS320C30 software development tools, a 
walkthrough, and installation information. 


C Compiler Operation 

Describes how to operate the C compiler and the CL30 program. Contains 
instructions for invoking CL30, which compiles, assembles, and links a C 
source file, and for invoking the individual compiler components. Discusses 
the interlist utility, filename specifications, compiler options, and using the 
linker and archiver with the compiler. 


TMS320C30 C Language 
Discusses the differences between the C language supported by the 
TMS320C30 C compiler and standard Kernighan and Ritchie C language. 


Runtime Environment 

Contains technical information on how the compiler uses the TMS320C30 
architecture; discusses memory and register conventions, stack organiza- 
tion, function-call conventions, system initialization, and TMS320C30 C 
compiler optimizations; provides information needed for interfacing assem- 
bly language to C programs. 


Runtime-Support Functions 

Describes the header files that are included with the C compiler, as well as 
the macros, functions, and types that they declare, summarizes the 
runtime-support functions according to category (header), and provides an 
alphabetical reference of the runtime-support functions. 
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Appendix A Compiler Error Messages 


Provides the format of compiler error messages and lists all the fatal error 
messages. 


Appendix B Preprocessor Directives 
Describes the standard preprocessor directives that the compiler supports. 


Appendix C Increasing Code Generation Efficiency 


Presents guidelines for writing C programs that take advantage of the 
TMS320C30 C compiler optimizations. 


Related Documentation 


You should obtain a copy of The C Programming Language (first edition), 
by Brian W. Kernighan and Dennis M. Ritchie, published by Prentice-Hall, 
Englewood Cliffs, New Jersey, 1978, to use with this manual. 


You may find these two books useful as well: 


Programming in C Kochan, Steve G. Hayden Book Company. 


Advanced C: Techniques and Applications Sobelman, Gerald E. and 


David E. Krekelberg. Que Corporation, 1985. 


The following books, which describe the TMS320C30 and related support 
tools, are available from Texas Instruments: 


a 


The Third-Generation TMS320 User’s Guide (literature number 
SPRU031) discusses hardware aspects of the TMS320 family 
third-generation devices, including the TMS320C30. Topics in this 
user’s guide include pin functions, architecture, stack operation, and 
interfaces; the manual also includes the TMS320C30 assembly lan- 
guage instruction set. 


The TMS320C30 Assembly Language Tools User’s Guide (litera- 
ture number SPRU035) describes the assembly language tools (as- 
sembler, linker, archiver, and code conversion utility), assembler 
directives, macros, common object file format, and symbolic debugging 
directives. 
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Style and Symbol Conventions 
This document uses the following conventions: 


La Program listings, program examples, interactive displays, filenames, 
and symbol names are shown in a special font. Examples use a bold 
version of the special font for emphasis. Here is a sample program seg- 


ment: 
extern float sine[]; /* This is the object * / 
float *sine p = sine; /* Declare a C pointer 
to: point to at x / 
f = sine p[4]; /* Access sinelikea 
normal array */ 


La In syntax descriptions, the instruction, command, or directive is in a 
bold face font and parameters are in /talics. Portions of a syntax that 
are in bold face should be entered as shown; portions of a syntax that 
are in italics describe the type of information that should be entered. 
Here is an example of a command syntax: 


Ink30 filenames 


Ink30 is acommand. This command has one parameter, indicated by 
filenames. When you use |nk30, the first parameter must be a filename. 


La Square brackets ([ and ] ) identify an optional parameter. If you use an 
optional parameter, you specify the information within the brackets; you 
don’t enter the brackets themselves. Here’s an example of acommand 
that has two optional parameters: 


cl30 [options] [filenames] 


cl30 is acommand. This command has two optional parameters, indi- 
cated by options and filenames. When you use cl30, no parameters are 
necessary; however, if you do indicate parameters, they should appear 
in this order. 
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Chapter 1 


Introduction and Installation 


The TMS320C30 is a high-performance CMOS floating-point microproces- 
sor, optimized for digital signal processing applications. The TMS320C30 
is amember of the third generation of TMS320 family digital signal proces- 
sors. 


The TMS320C30 is fully supported by a complete set of hardware and soft- 
ware development tools, including a C compiler, an assembler, linker, and 
archiver, a software simulator, and a full-speed emulator. Section1.1 
describes these tools. 


This reference guide describes the TMS320C30 C compiler. Its main pur- 
pose is to present the details and characteristics of this particular C compil- 
er; itassumes that you already know how to write C programs. We suggest 
that you obtain a copy of The C Programming Language, by Brian W. 
Kernighan and Dennis M. Ritchie (published by Prentice-Hall); use this ref- 
erence guide as a supplement to the Kernighan and Ritchie book. 


Texas Instruments provides a hotline to assist you with technical questions 
about the TMS320 family products and development tools. The phone num- 
ber is 713-274-2320. 


The TMS320C30 C compiler can be installed on the following systems: 


Li IBM-PC/PC-DOS and compatibles 

La =VAX/VMS 

Ca =VAX/ULTRIX 

C4 Workstations with UNIX 

14 Macintosh with MPW 

Topics in this Chapter include: 

Section Page 
1.1 Software Development Tools Overview ................-.-. 1-2 
lwo “Geng: Slated wat3i:4c tas eh ose iwadeehis tenes 1-7 


1.4 Compiler Installation ......... 0... 0c ccc cee eee 1-9 
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1.1 Software Development Tools Overview 


Figure 1—1 illustrates the TMS320C30 software development flow. The 
shaded portion of the figure highlights the typical software development 
path; the other portions are optional. 


Figure 1-1. TMS320C30 Software Development Flow 
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The following list describes the tools that are shown in Figure 1-1. 


Ly The C compiler accepts C source code and produces TMS320C30 
assembly language source code. A CL30 program and an interlist util- 
ity are included in the compiler package. The CL30 program enables 
you to automatically compile, assemble, and link source modules. The 
interlist utility intereweaves C source statements with assembly lan- 
guage output. Chapter 2 describes compiler, CL30, and interlist invoca- 
tion and operation. 


The assembler translates assembly language source files into ma- 
chine language object files. 


Li The archiver allows you to collect a group of files into a single archive 
file. (An archive file is also called a /ibrary.) Additionally, the archiver 
allows you to modify a library by deleting, replacing, extracting, or add- 
ing members. One of the most useful applications of the archiver is to 
build a library of object modules. 


One object library, rts.lib, is shipped with the C compiler. This library 
contains standard runtime-support functions, compiler utility functions, 
and math functions that can be called in C programs. You can also 
create your own object libraries. To use an object library, you must 
specify the library name as linker input; the linker will include the mem- 
bers in the library that define the functions you call in a C program. 


La Thelinker combines object files into a single executable object module. 
As it creates the executable module, it performs relocation and resolves 
external references. The linker accepts relocatable COFF object files 
and object libraries as input. 


La The main purpose of this development process is to produce a module 
that can be executed in a TMS320C30 target system. You can use one 
of several debugging tools to refine and correct your code before down- 
loading it to a TMS320C30 system. These debugging tools share a 
common screen-oriented interface that displays and maintains ma- 
chine status information and controls execution of the system that is be- 
ing developed. Note that only /inked object files can be executed. 


m The simulator is a software program that simulates TMS320C30 
functions. The simulator can execute linked COFF object modules. 


m™ The XDS emulator is a PC-resident, realtime, in-circuit emulator 
with the same screen-oriented interface as the software simulator. 


Li Anobject format converter is also available; it converts a COFF object 
file into an Intel word, extended Tektronix hex, or Tl-tagged object for- 
mat file that can be downloaded to an EPROM programmer. 
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A software platform is also available for augmenting your TMS320C30 C 
compiler: 


Lk SPOX 


SPOX is a high-level software interface designed specifically for digital 
signal processing and control applications. It is a system of software 
components that you can combine according to your needs. SPOX pro- 
vides the common operating system functions of memory manage- 
ment, I/O, and multi-tasking. SPOX differs from traditional operating 
systems by supplying an optimized math and DSP library as well as 
real-time stream I/O. SPOX is available from Spectron Microsystems, 
Incorporated. 
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1.2 TMS320C30 C Compiler Overview 


The TMS320C30 C compiler is a full-feature optimizing compiler that trans- 
lates standard Kernighan and Ritchie C programs into TMS320C30 
assembly language source. The following list describes key characteristics 
of the compiler: 


Ld 


Standard Kernighan and Ritchie C with Extensions 


The compiler compiles standard C programs as defined by Kernighan 
and Ritchie’s The C Programming Language (first edition). The com- 
piler supports these standard extensions: enumeration types, structure 
assignments, passing structures to functions, and returning structures 
from functions. A future release of the compiler will support the full ANSI 
standard. For more information, refer to Chapter 3. 


32-Bit Data Sizes 


All data sizes (char, short, int, long, float, and double) are 32 bits. This 
allows all types of data to take full advantage of the TMS320C30’s 
32-bit integer and floating-point arithmetic capabilities. For more infor- 
mation, refer to Section 3.2 on page 3-4. 


Big and Small Memory Models 


The compiler supports two memory models. The small memory model 
enables the compiler to efficiently access memory by restricting the 
global data space to a single 64K-word data page. The big memory 
model allows unlimited space. For more information, refer to Section 
4.1 on page 4-2. 


Optimization 


The compiler uses several advanced techniques for generating 
efficient, compact code from C source. For more information the C 
compiler’s optimization techniques, refer to Section 4.9 on page 4-28 
and Appendix C. 


Assembly Source Output 


The compiler generates assembly language source that is easily in- . 
spected, enabling you to see the code generated from the C source 
files. 


COFF Object Files 


The COFF format allows you to define you system’s memory map at link 
time. This maximizes performance by enabling you to link C code and 
data objects into specific memory areas. COFF also provides rich sup- 
port for source-level debugging. 
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ROM-able Code 


For stand-alone embedded applications, the compiler enables you to 
link all code and initialization data into ROM. 


ANSI Standard Runtime Support 


The compiler package comes with acomplete runtime library. All library 
functions conform to the ANSI C library standard. The library includes 
functions for string manipulation, dynamic memory allocation, data con- 
version, timekeeping, trigonometry, exponential, and hyperbolic 
functions. Functions for I/O and signal handling are not included be- 
cause these are target-system specific. For more information, refer to 
Chapter 5. 


Flexible Assembly Language Interface 


The compiler has straight-forward calling conventions, allowing you to 
easily write assembly and C functions that call each other. For more in- 
formation, refer to Chapter 4. | 


CL30 Compiler Shell Program 


The compiler package includes a CL30 shell program which enables 
you to compile, assemble, and link programs in a single step. For more 
information, refer to Chapter 2. 


Source Interlist Utility 


The compiler package includes a utility that interlists your original C 
source statements into the assembly language output of the compiler. 
This utility provides you with an easy method for inspecting the 
assembly code generated for each C statement. For more information, 
refer to Section 2.7 on page 2-14. 
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1.3 Getting Started 


The TMS320C30 C compiler has three parts: a preprocessor, a parser, and 
a code generator. The compiler produces a single assembly language 
source file that must be assembled and linked. The simplest way to compile, 
assemble, and link a C program is to use the CL30 program which is 
included with the compiler. This section provides a quick walkthrough so 
that you can get started without reading the entire reference guide. 


Create a sample file called function.c that contains the following 


1) 


2) 


code: 


Getting Started 
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/* function.c 


/* (Sample file for walkthrough) 


ey 
wed 


[ RRKKKKRKKKKKKKKKKK KKK KKK KK KKK KKK KKK KK / 


#tinclude “stdlib.h” 


int abs(i) 
pis gy wis 
{ 


register int temp = i; 


1£ (temp < 0) temp = —-temp; 


return (temp); 


Invoke CL30 to run the compiler and assembler. 
e130 function [=] 


CL30 prints the following information as it compiles the program: 


[function] 


C Pre-Processor, Version 2.00 
(c) Copyright 1987, 1989, Texas Instruments 
TMS320C30 C Compiler, Version 2.00 
(c) Copyright 1987, 1989, Texas Instruments 


“Function.c” ==> abs 


TMS320C30 C Codegen, Version 2.00 


(c) Copyright 1987, 1989, Texas Instruments 
“function.c” ==> abs 
TMS320C30 COFF Assembler, Version 2.00 
(c) Copyright 1987, 1989, Texas Instruments 
PASS 1 
PASS 2 


No Errors, No Warnings 


CL30 runs the three compiler passes and the assembler as follows: 


cpp30 — C Preprocessor 
cc30 — #£=C Parser 

cg30 — Code Generator 
asm30 — Assembler 
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By default, CL30 deletes the assembly language output file from the 
compiler after it’s assembled. If you wish to inspect the assembly lan- 
guage output of the compiler, use the —k option on CL30. 


Also by default, CL30 creates a COFF object file as output; however, 
if you use the —z option, the output will be an executable object module. 
The following examples walk you through the two ways of achieving an 
executable object module: 


a) The example above creates an object file called function.obj. To 
create an executable object module, link the object file with the 
runtime-support library rts.1ib: 


Ink30 -c function -o function.out -1 rts.lib [= 


This examples uses the -c linker option because the code came 
from a C program. The —I option tells the linker that the input file 
rts.libis an object library. The —o option names the output mod- 
ule, function. out; If you don’t use the —o option, the linker names 
the output module a. out. 


b) Inthis example, CL30 runs the linker directly by using the —z option, 
followed by the linker options. 


cl130 function -zg -o function.out -1l rts.lib [I 


This example runs the three compiler passes, the assembler, and 
the linker as follows: 


cpp30 — C Preprocessor 
cc30 —- #£=C Parser 

cg30 — Code Generator 
asm30 — Assembler 


Ink30 — Linker 


The TMS320C30 includes an interlist utility. This program inter- 
weaves the C source statements as comments in the assembly lan- 
guage compiler output, allowing you to inspect the assembly language 
generated for each line of C. To run the interlist utility, invoke CL30 with 
the —s option. For example: 


c130 function -z -s -o function.out -l rts.lib [| 


The output of the interlist utility is written to the assembly language file 
created by the compiler. (The CL30 —s option implies —k; that is, when 
you use the interlist utility, the assembly file is automatically retained.) 


For more information about invoking the C compiler, the interlist utility and 
the CL30 program, refer to Chapter 2. 
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1.4 Compiler Installation 


This section contains step-by-step instructions for installing the 
TMS320C30 C compiler. Refer to the following sections for installation infor- 


mation: 

Section Installing on... Page 
1.4.1 PEI Sed ai wrote Ahan ds 0 ad a ae ee ee ee 1-9 
1.4.2 DEC VAX/VMS. .......... ede rats Gea a ening apenas 1-10 
1.4.3 VAX/WLTRUX gist oe ee oe ea he Shs as 1-10 
1.4.3 Workstations with Unix .. 2... 0.0.0... 0... ee eee eee 1-10 
1.4.4 Macintosh with MPW ................ 2.202 eee 1-11 


1.4.1. Installing the C Compiler on IBM-PCs with PC-DOS 
The C compiler package is shipped on double-sided, dual-density diskettes. 
The compiler executes in batch mode and requires 512K bytes of RAM. 


These instructions are for both hard-disk systems and dual floppy drive 
systems (however, we recommend that you use the compiler on a hard-disk 
system). On a dual-drive system, the PC-DOS system diskette should be 
in drive B. The instructions use these symbols for drive names: 


A: Floppy disk drive for hard disk systems; source drive for dual-drive 
systems. 

B: Destination or system disk for dual-drive systems. 

C: Winchester (hard disk) for hard-disk systems. 


Follow these instructions to install the software: 
1) Make backups of the product diskettes. 


2) Create adirectory to contain the C compiler. If you’re using a dual-drive 
system, put the disk that will contain the tools into drive B. 


Ci On hard-disk systems, enter: 
MD C:\C30TOOLS [Lal 


La On dual-drive systems, enter: 
MD B:\C30TOOLS [uf 


3) Copy the C compiler package onto the hard disk or the system disk. Put 
the product diskette in drive A; if you’re using a dual-drive system, put 
the disk that will contain the tools into drive B. 


Li On hard-disk systems, enter: 
COPY A:\*.* C:\C30TOOLS\*.* [Kul 


C4 On dual-drive systems, enter: 
COPY A:\*.* B:\C30TOOLS\*.* [| 
4) Repeat steps 1 through 3 for each product diskette. 
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1.4.2 Installing the C Compiler on VAX/VMS 


The TMS320C30 C compiler tape was created with the VMS BACKUP utility 
at 1600 BPI. These tools were developed on version 4.5 of VMS. If you are 
using an earlier version of VMS, you may need to relink the object files; refer 
to the release notes for relinking instructions. 


allocate 


Follow these instructions to install the compiler: 


1) 
2) 


Mount the tape on your tape drive. 


Execute the following VMS commands. Note that you must create a 
destination directory to contain the package; in this example, 
DEST:directory represents that directory. Replace Tape with the 
name of the tape drive you are using. 


TAPE: 


mount/for/den=1600 TAPE: 
backup 


dismount 
dealloc 


3) 


TAPE:c30.bck/select=[master.c30c...] DEST: [directory...] 
TAPE: 
TAPE: 


The product tape contains a file called setup.com. This file sets up VMS 
symbols that allow you to execute the tools in the same manner as other 
VMS commands. Enter the following command to execute the file: 


$ @setup DEST:directory S| 


This sets up symbols that you can use to call the various tools. As the file 
is executed, it will display the defined symbols on the screen. 


1.4.3 Installing the C Compiler on Workstations with UNIX 


The TMS320C30 C compiler product tape was made using the tar utility. 
Follow these instructions to install the compiler: 


1) 
2) 


3) 


Mount the tape on your tape drive. 


Make sure that the directory you store the tools in is the current 
directory. 


Enter the tar command for your system; for example, 


tar x [=] 


This copies the entire tape into the directory. The tar command varies 
from system to system; consult your system documentation for proper 
use of the tar command. | 
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1.4.4 Installing the C Compiler on Macintosh with MPW 


The TMS320C30 compiler package runs only under the Macintosh 
Programmer’s Workshop (MPW). MPW is a complete software develop- 
ment environment for Macintosh Computers that can be purchased through 
for Apple. These tools cannot be run on a Macintosh without MPW. 


The C compiler is shipped on a double-sided, 800k, 3 1/2” diskette. The disk 
contains three folders: 


Tools Includes Libraries 


Use the Finder to display the disk contents and copy the files into your MPW 
environment: 


1) The Toolsdirectory contains allthe programs and the batch files for run- 
ning the compiler. Copy this directory in with your other MPW tools 
(MPW tools are usually in the folder {MPW}Tools.) 


2) The Includes directory contains the header files (.h files) for the run- 
time-support functions. Many of these files have names that conflict with 
commonly-used MPW header files, so you should keep these header 
files separate from the MPW files. Copy the contents of the /ncludes di- 
rectory into a new folder, and use the C_DIR environment variable. For 
information describing how to create a path to this folder, refer to Sec- 
tion 2.8.1.1 on page 2-18. 


3) The Libraries folder contains the compiler’s runtime-support object and 
source libraries. You can copy these files into the folder that you created 
for the header files, or you can copy them into a new folder. If you copy 
them into a new folder, use the C_DIR environment variable to create 
a path to this folder as well. 
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Chapter 2 


C Compiler Operation 


The TMS320C30 C compiler is made up of three programs: the 
preprocessor, the parser, and the code generator. After compiling a pro- 
gram, you must assemble and link it with the TMS320C30 assembler and 
linker. The CL30 program, included with the compiler, enables you to auto- 
matically compile, assemble, and link one or more source modules. 


The compiler package also includes a utility that interlists your original C 
source statements into the assembly language output of the compiler, 
enabling you to inspect the assembly code generated for each C statement. 
The interlist utility is explained in Section 2.7. 


lf you choose to run the three compiler steps individually, Section 2.8 de- 
scribes how to runthe preprocessor, parser, and code generator 
individually. 


Topics in this chapter include: 


Section Page 
2.1 C Compiler Overview ............. 0. ccc cee ee eens 2-2 
2.2 Invoking the C Compiler ............. 0.0 cee eee ee eee 2-3 
2.3 Filename Specifications ......... 0.0... ees 2-4 
Zi. SODNONS. 6.220 ook Spies ken ans Heke 84 care we 2-6 
2.5 Running the Linker with CL30 ..................--0005- 2-11 
2.6 Using the C_OPTION Environment Variable .............. 2-13 
2.7 Interlist Utility Operation ............ 0.0. cece eee eee 2-14 
2.8 Operating the Preprocessor, the Parser, and the Code 

Generator Individually ........... 0.0 cc eee ee eens 2-16 
2.9 “Winking a:© Proglam: aaiad Cesk ce hteaeawstedd da era Se 5 2-24 
2.10 Using the Archiver with OC 1.0... . eee ee ee 2-28 
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2.1 


C Compiler Overview 


The TMS320C30 C compiler is made up the preprocessor, the parser, and 
the code generator. 


After you have compiled a program, you must assemble and link it with the 
TMS320C30 assembler and linker. A program called CL30 is provided with 
the compiler which automatically runs one or more source modules through: 


La the three compiler passes, 
[4 the assembler, and 
Li if the —z option is used, the linker. 


Figure 2—1 illustrates CL30 with and without the —z option. You can invoke 
CL30 with compiler, assembler, and linker options, and CL30 will automati- 
cally vector the options to the appropriate program. You may also set CL30 
default options by using the C_OPTION environment variable; these de- 
faults options are used every time you run CL30. 


Figure 2-1. CL30 Overview 
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2.2 Invoking the C Compiler 


To run the compiler, enter 


cl30 is the command that invokes the compiler and assembler. 

options affect the way the compiler processes input files. 

filenames are oneor more C source files, assembly source files, or ob- 
ject files. 

—Z option that runs the linker. 


link_options affect the way the linker processes input files. 


Options and filenames can be specified in any order on the command line, 
but if you use the —z option, it must follow all filenames and compiler options. 
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2.3 Filename Specifications 


The input files specified on the command line can be C source files, assem- 
bly source files, or object files. CL30 uses filename extensions to determine 
the file type. 


Extension File Type File Description 
ic compiled, assembled, and (linked) 


asm assembly assembled and (linked) 
source 
.s* (extension assembly assembled and (linked) 
begins with s) source 
.o* (extension object file linked 
begins with o) 


none (.c assumed) | C source compiled, assembled, and (linked) 


Extensions and filenames are not case sensitive. Files without extensions 
are assumed to be C source files anda .c extension is appended. You can 
override these file type interpretations by using the —f option as follows: 


—fa file for an assembly file 
—fc file for a C source file 
—fo file for an object file 


You can use wildcard specifications to compile multiple files. Wildcard 
specifications vary by system; use the appropriate form. 


You can compile and assemble source files with a single command. Here 
are some examples. 


1) To compile all the files in a directory, enter: 


c130 ¥*.c [=] 


2) Tocompile a source file named hilev.c and two assembly files called 
lowlev.asmand lowlev2.asm, enter: 


c130 hilev lowlevl.asm lowlev2.asm (=) 
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Filename Specifications 


As CL30 encounters each source file, it prints the filename in square 
brackets [for c files] or angle brackets <for asm files>. Progress information 
is output from each of the compiler passes unless the —q option is specified. 
If you use the —q option, only the source filenames print. If you use the —-qq 
option, no progress information prints except error messages. For example, 
the output from compiling a single module might be: 


$ c130 symtab [Li] 

[symtab] 

C Pre-Processor Version 2.00 

(c) Copyright 1987, 1989, Texas Instruments Incorporated 

TMS320C30 C Compiler Version 2.00 

(c) Copyright 1987, 1989, Texas Instruments Incorporated 
“symtab.c”:==> main 
“symtab.c”:==> lookup 

TMS320C30 C Codegen Version 2.00 

(c) Copyright 1987, 1989, Texas Instruments Incorporated 
‘“symtab.c”:== main 
“symtab.c”:== lookup 

TMS320C30 COFF Assembler Version 2.00 

(c) Copyright 1987, 1989, Texas Instruments Incorporated 
PASS 1 
PASS 2 


No Errors, No Warnings 


Using the quiet option (-q) to compile multiple files, you might get: 


$ c130 -q symtab file seek.asm [Li/ 
[symtab] 


[file] 
<seek.asm> 
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2.4 Options 


Command line options control the operation of both CL30 and the programs 
it calls. | 


2.4.1 Option Conventions 


Options are either single letters or two-letter pairs, are not case sensitive, 
and are preceded by ahyphen. Single-letter options without parameters can 
be combined: for example, —sgq is equivalent to —s —g —q. Two-letter pair 
options that have the same first letter can be combined: for example, —mrb 
is equivalent to —-mr and —mb. Options that have parameters, such as —d, 
must be specified separately. 


Table 2—1 summarizes the following options: general, preprocessor, as- 
sembler, runtime model, filename, linker, and environment variable options. 
Section 2.4.2 provides an in-depth description of each of these options. 


Table 2-1. Options Summary Table 


General Options 
Usage: cl30 [—options] filenames. . . [—z link_options. . . ] 


= | nolinking(negates-z) || -q_ | quiet 

z | symbolicdebugging || -s_— | C-source interlist 
—i<dir> | #include search path || -uname undefine name 
-k [ keep.asmfile ff =z 


—n compile only 


—z link, options follow 


Preprocessor Options —p<options. . . > 
—pc preprocess only —pp no #line directive 


Assembler Options —a<options. . . > 
cross-reference file 


preprocess first 


Runtime Model Options 


—ma assumes aliased variables 

—mb enables the big memory model 

—mm enables the short multiply 

—mn | normal optimization, even with debug 
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Table 2-1. Options Summary Table (Continued) 


Runtime Model Options (continued) 


—mr lists register use information 
—Mv volatile variables 
—mx avoids TMX silicon bugs 


~f options (File Specifiers) 


—fa file assembly language file 
(default for .asm or .s*) 


-tc file C source file 
(default for .c or no ext) 


—fo file object file (default for .o*) 


Linker Options (all options following —z go to the linker) 


-2 [absolute output || ar 

-c | ROMinitialization |} -cr ~=—S————s|,s« RAM initialization 

cesym___|_entrypoint | tual tillvalue 

“h [global symbols static || idir___ | library search path 
| =mfle 
el 


—ar relocatable output 


“ib “nfl opslenae 


—0 file output filename —r relocatable output 
—S strip symbol table —usym undefine sym 


Environment Variables 
setenv C_OPTION “options” to set default options 
setenv C_DIR “dirs” to set cpp and linker search paths 


2.4.2 Option Descriptions 


This section contains descriptions of general, compiler, preprocessor, as- 
sembler, runtime model, and linker options. 


Li General Options 


—C suppresses the linking option; it causes CL30 to not run the 
linker even if —z is specified. This option is especially useful when 
you have —z specified in the C_OPTION environment variable 
and you don’t want to link. For more information, refer to Section 
2.6 on page 2-13. 
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causes the compiler to generate symbolic directives for use with 
a high-level language debugger. 


adds dir to the list of directories to be searched for #include files. 
You can use this option multiple times to define several 
directories; be sure to separate —/ options with spaces. Note that 
if you don’t specify a directory name, the preprocessor ignores 
the —i option. 


keeps the .asm file. Normally, CL30 deletes the output assembly 
language file after assembly is finished, but using —k allows you 
to retain the assembly source output from the compiler. 


causes CL30 to compile only. If you use —n, the specified source 
files are compiled but not assembled or linked. This option over- 
rides —z and —c. The output of —n is assembly source output from 
the compiler. 


suppresses banners and progress information from all the tools. 
Only source filenames and error messages are output. 


suppresses all output except error messages. 


invokes the interlist utility, which interweaves C source state- 
ments into the assembly language output of the compiler, allow- 
ing you to inspect the code generated for each C statement. This 
option implies that the —k option is specified. For more informa- 
tion about the interlist utility, refer to Section 2.7 on page 2-14. 


enables the linking option; it causes CL30 to run the linker on 
specified object files. —-z must follow all source files and compiler 
options on the commandline. All arguments that follow —z on the 
command line are passed to and interpreted by the linker. 


—f options override default interpretations for source file exten- 
sions. If your naming conventions do not conform to those of 
CL30, you can use -f options to specify exactly which files are C 
source files, assembly files, or object files. You can insert an op- 
tional space between the -f option and the filename. 

—fafile This file is an assembly source file. 

—fcfile This file is C source file. 

—fofile This file is an object file. 


If you have a C source file called cfile.s and an assembly file 
called assy, use —f to force the correct interpretation: 


c130 -fc cfile.s -fa assy 


Note that -f cannot be applied to a wildcard file specification. 
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Compiler Options 


—dname[=def] pre-defines name for the preprocessor. This is equiva- 


lentto inserting #define name def atthe top of each C 
source file. If the optional [deff if omitted, 
—dname[=def] sets name equal to 1. 


—uname undefines the predefined constant name. 


Preprocessor Options 


causes the compiler to preprocess only. —pc runs the preproces- 
sor on the specified source files and retains the comments. The 
remaining compiler passes, the assembler, and the linker are not 
run. 


suppresses line and file information. —pp causes the preproces- 
sor to suppress its normal location directives of the form: 
#123 file.c. 


—pp is sometimes useful when compiling machine-generated 
code. 


Assembler Options 


invokes the assembler with the —| (lowercase “L”) option to pro- 
duce an assembly listing file. 


enables preprocessing. —ap runs the C preprocessor on the 
assembly source before assembling them. 


retains labels. Label definitions are written to the COFF symbol 
table for use with symbolic debugging. 


invokes the assembler with the —x option to produce a symbolic 
cross-reference in the listing file. 


For more information about assembler options, see Section 4.2, page 
4-3 in the TMS320C30 Assembly Language Tools User’s Guide. 


Runtime Model Options 


—ma 


assumes variables are aliased. The compiler assumes that 
pointers may alias (point to) named variables and therefore 
aborts register optimizations whenever an assignment is made 
through a pointer. 


selects the big memory model. —mb allows unlimited space for 
global data, static data, and constants. In the small memory 
model, which is the default, this space is limited to 64k words. For 
more information, refer to Section 4.1 on page 4-2. 
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enables the short multiply. -mm generates MPY1 instructions for 
integer multiples rather than runtime-support calls. If your appli- 
cation does not need 32x32-bit integer multiplication, use —-mm 
to enable the MPYI instruction because it is significantly faster 
(but it performs only 24x24-bit multiplication). For more informa- 
tion, refer to Section 4.8 on page 4-26. 


normal optimazation, even with debug. When you generate sym- 
bolic debugging information with the —g switch, the code genera- 
tor disables certain optimizations that inhibit debugging. You can 
use —mn to re-enable these optimizations and generate exactly 
the same code as without —g. 


lists register use information. After the code generator compiles 
each C statement, —mr lists register contents tables as com- 
ments in the assembly file. —-mr is useful for inspecting code that 
is difficult to follow due to register tracking optimizations. 


assumes variables are volatile. Disables register tracking optimi- 
zations. Variables are always read from memory each time they 
are accessed. 


avoids early silicon bugs. -mx enables the code generator to 
work around some of the known hardware bugs in early 
TMX320C30 devices. 


Linker Options 


All command line input following —z is passed to the linker. Table 2-1, 
on page 2-6, summarizes the linker options. For more information 
about linker options, see Section 9.3, page 9-4, in the TMS320C30 
Assembly Language Tools User’s Guide. 
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2.5 Running the Linker with CL30 


CL30, by default, does not run the linker; however, youcan enable the linker 
by using the —z option. 


Figure 2-2. CL30 Overview with the Linker 
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2.5.1 -z CL30 option 
When using —z to enable linking, remember: 
[i -—C suppresses —z, so do not use -c if you want linking enabled, 


La —z must follow all source files and compiler options on the command 
line, and 


L4 -—z divides the commandline into compiler options (before —z) and linker 
options (following —z) 


All arguments that follow —z on the command line are passed to the linker. 
These arguments can be linker command files, additional object files, linker 
options, or libraries. 
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The order in which the linker processes arguments can be important, 
especially for command files and libraries. When you use CL30 to run the 
linker, it passes arguments to the linker in the following order. 


1) Object file names from the command line, 

2) Arguments following —z on the command line, and 

3) Arguments following —z from the C_OPTION environment variable. 
For example, to compile and link all the .c files in a directory enter: 
cl130 -sq -mm *.c -z c.cmd -o prog.out -1 rts.lib 


First, c/30 compiles all the files with “.c extensions using the —sq and —-mm 
options. Second, because —z is specified, the linker runs the resulting object 
files using the the linker command file c.cmd, the —o option to name the out- 
put file, and the —/ option to include the runtime-support library. 


For more information about linker operation, refer to Section 2.9 on page 
2-24 in this manual and Chapter 9, Linker Description, in the TMS320C30 
Assembly Language Tools User’s Guide. For more information about linker 
options, refer to Section 9.3 in the TMS320C30 Assembly Language Tools 
User's Guide. 


2.5.2  -c CL30 Option 


2.5.3 
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Passing the —c option to CL30 overrides —z and disables linking. This option 
is helpful when you have specified —z in the C_OPTION environment vari- 
able and want to selectively disable linking with —c on the command line. 


—c and —cr Linker Options 


The —-c linker option has a different function than, and is independent of, 
the —c CL30 option. By default, CL30 automatically uses the —c option that 
tells the linker to use C source linking conventions (ROM model of initializa- 
tion). If you want to use —cr (RAM model of initialization) rather than —c, you 
Can pass —cr as a linker option. 
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2.6 Using the C_OPTION Environment Variable 


You can set up default options for CL30 using the C_OPTION environment 
variable. After CL30 reads the entire command line, it reads the C_OPTION 
environment variable and processes it. 


Options in the environment variable are specified in the same way and have 
the same meaning as they do on the command line. 


For example, if you want to always run quietly, enable symbolic debugging, 
and link, then set up the C_OPTION environment variable as follows: 


DOS set C_OPTION=—qg —z 

UNIX setenv C_OPTION ”—ag —z” 

VAX/VMS assign "—qg —z” C_OPTION 

MPW set C_OPTION ”"—qg —z”; export C_OPTION 


Using the —z option in the environment variable enables linking. Inthe exam- 
ples above, each time you run CL30, it will run the linker. Any options follow- 
ing —z on the command line are passed to the linker; likewise, any options 
following —z on the options line are passed to the linker. This enables you 
to use the environment variable to specify default compiler and linker op- 
tions and then specify additional compiler and linker options on the CL30 
command line. If you have set —z in the environment variable and want to 
compile (or assemble) only, use the —c option of CL30. These additional 
examples assume C_OPTION is set as shown above: 

CLo0 eee ; compiles and links 

Cis0 Hoe sc ; only compiles 

C130. Fee. =z. es cme ; compiles and links using a command file 
cl130 -c *.c -z c.cmd ; only compiles (-c overrides -z) 
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2.7 


2.7.1 


Interlist Utility Operation 


The compiler package includes a utility that interlists your original C source 
statements into the assembly language output of the compiler. The interlist 
utility enables you to inspect the assembly code generated for each C state- 
ment. 


Invoking the Interlist Utility Using the -s CL30 Option 


The easiest way to invoke the interlist utility is to use the -s CL30 option. 
To compile and run the interlist utility on a program called function.c, en- 
ter: 


c130 -s function 


The interlist runs a separate pass between the code generator and the as- 
sembler. It reads both the assembly and C source files, merges them, and 
writes the C statements into the assembly file as comments (beginning with 
>>>>). The output assembly file is assembled normally. The —s option auto- 
matically prevents CL30 from deleting the interlisted assembly language 
file. 


Figure 2-3 shows a typical interlisted assembly file. 


Figure 2-3. An Example of an Interlisted Assembly File 
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;>>>> main () 
;>>>> Ln Aor 3 
KEREKKKKKKEKKKKEKKKKKRKKKRKRKKKKKRKKKKKKKKKKKKEKK 


< FUNCTION DEF : main e 
KKKKKKKKKKKKKKKKKKK KKK KKK KKK KK KKK KKKKKKKKKK 


_main: 


FP 
SP, FP 
2, SP 

i += J; 
*+FPP(1),R3 
*+FP(2),R3 
R3, *+FP (1) 

J = 1+ 123; 
LZ S¢Ro 
R3, *+FP (2) 
2,SP 
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Interlist Utility Operation 


2.7.2 Invoking the Interlist Utility Outside CL30 


Even if you are not using CL30, you can still use the interlist utility. After you 
have compiled a program, you can run the interlist utility as a standalone 
program from the commandline. To run the interlist utility from the command 
line, the syntax is: 


clist is the command that invokes the interlist utility. 
asmfile is the assembly language output from the compiler. 
outtile names the interlisted output file. If you omit this, the file has 


the same name as the assembly file with the the extension .ci. 
options control the operation of the utility as follows: 


—b removes blanks and useless lines (lines containing 
comments or lines containing only {or }). 


—r removes symbolic debugging directives. 
—q removes banner and status information. 


The interlist utility uses the .line directives produced by the code generator 
to associate assembly code with C source. For this reason, you must 
specify symbolic debugging when compiling the program if you want to in- 
terlist it. If you do not want the debugging directives in the output, use the 
—r option to remove them from the interlisted file. 


The following example shows how to compile and interlist function.c. 


Function Comments 
compile cl30 —gk function compile, use debug, keep assembly 


interlist clist —r function interlist, remove debug 


The output from this example is function.cl. 
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2.8 Operating the Preprocessor, the Parser, and the 
Code Generator Individually 


The TMS320C30 C compiler is made up of three distinct programs: the pre- 
processor, the parser, arid the code generator. This section provides infor- 
mation about how to run the individual programs. 


Li The input for the preprocessor is a C source file (as described in 
Kernighan and Ritchie). The preprocessor produces a modified version 
of the source file. Section 2.8.1 describes how to run the preprocessor. 


La The input forthe parser is the modified source file produced by the pre- 
processor. The parser produces an intermediate file. Section 2.8.2 
describes how to run the parser. 


La The input for the code generator is the intermediate file produced by 
the parser. The code generator produces an assembly language source 
file. Section 2.8.3 describes how to run the code generator. 


Figure 2-4. Compiling a C Program 
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C source 


file (.c) 


= modified source intermediate file assembly language 
| file (.cpp) (.if) file (.asm) 


Refer to the following sections for more information: 


Section | Page 
2.8.1 Preprocessing C Code ............ cece eee 2-17 
eo.2e. (Parsing. COde-t 2. cide toadte seid tiaden doin Eeededes 2-21 
2.8.3 Generating Assembly Language Code ................ 2-22 
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2.8.1. Preprocessing C Code 


The first step in compiling a TMS320C30 C program is to invoke the C pre- 
processor. The preprocessor handles macro definitions and substitutions, 
#include files, line number directives, and conditional compilation. As 
Figure 2—4 shows, the preprocessor uses a C source file as input, and pro- 
duces a modified source file that can be used as input for the C parser. 


To invoke the preprocessor as a standalone program, enter: 


cpp30 is the command that invokes the preprocessor. 


input file names aC source file that the preprocessor uses as input. If 
you don’t supply an extension, the preprocessor assumes 
that the extension is .c. lf you don’t specify an input file, the 
preprocessor will prompt you for one. 


output file | names the modified source file that the preprocessor creates. 
If you don’t supply a filename for the output file, the preproces- 
sor uses the input filename with an extension of .cpp. 


options affect the way the preprocessor processes your input file.Op- 
tions are not case sensitive. Valid options include: 


—C copies comments to the output file. If you don’t use 
this option, the preprocessor strips comments. 


—dnamef[=def] See Compiler Options, page 2-9. 


—Iidir adds dir to the list of directories to be searched for 
#include files. See Compiler Options, page 2-9. 


—p suppresses line number and file information. 
—q suppresses the banner and status information. 


This preprocessor is described in Kernighan and Ritchie; additional infor- 
mation can be found in that book. The preprocessor supports the same pre- 
processor directives that are summarized in Appendix B of that book. All 
preprocessor directives begin with the character #, which must appear in 
column 1 of the source statement. Any number of blanks and tabs may 
appear between the # sign and the directive name. 
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The C preprocessor maintains and recognizes five predefined macro 
names: 


__LINE_ __ represents the current line number (maintained as a decimal 
integer). 


__FILE_ _ represents the current filename (maintained as a C string). 


_ _DATE_ _ represents the date that the module was compiled (main- 
tained as a C string). 


__TIME_ _ represents the time when this module was compiled (main- 
tained as a C string). 


_320C30 identifies the compiler as the TMS320C30 C compiler; this 
symbol is defined as the constant 7. 


You can use these names in the same manner as any other defined name. 
For example, 


print’ (’%s.%s",... “TIME. 5} - DATE. .)¢ 
would translate into a line such as: 
printf (%s $s”, "May 1 1989”, "13:58:17”); 


The preprocessor produces self-explanatory error messages. The line 
number and the filename where the error occurred are printed along with 
a diagnostic message. 


2.8.1.1 Specifying Alternate Directories for Include Files 


The #include preprocessor directive tells the preprocessor to read source 
statements from another file. The syntax for this directive is: 


#include ”filename’” or #include <filename> 


The filename names an include file that the preprocessor reads statements 
from; you can enclose the filename in double quotes or in angle brackets. 
The filename can be acomplete pathname or a filename with no path infor- 
mation. 


La If you provide path information for filename, the preprocessor uses that 
path and does not look for the file in any other directories. 


La If you do not provide path information and you enclose the filename in 
double quotes, the preprocessor searches for the file in this order: 


1) The directory that contains the current source file. (The current 
source file refers to the file that is being processed when the prepro- 
cessor encounters the #include directive.) 

2) Any directories named with the —i preprocessor option. 

3) Any directories set with the environment variable C_DIR. 
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La If you do not provide path information and you enclose the filename in 
angle brackets, the preprocessor searches for the file in: 


1) Any directories named with the —i preprocessor option. 
2) Any directories set with the environment variable C_DIR. 


Note that if you enclose the filename in angle brackets, the preproces- 
sor does not search for the file in the current directory. 


You can augment the preprocessor’s directory search algorithm by using 
the —i preprocessor option or the environment variable C_DIR. 


2.8.1.2 —i Preprocessor Option 


The —i preprocessor option names an alternate directory that contains 
include files. The format of the —i option is: 


cpp30 -i pathname 


You can use up to 10 -i options per invocation; each —i option names one 
pathname. |In C source, you can use the #include directive without specify- 
ing any path information for the file; instead, you can specify the path infor- 
mation with the —i option. For example, assume that a file called source.c 
is in the current directory; source.c contains the following directive state- 
ment: 


#include “alt.c” 


The table below lists the complete pathname for ait .c and shows how to 
invoke the preprocessor; select the row for your operating system. 


Pathname for alt.c Invocation Command 
DOS e:\C30\files\alt.c | cpp30 -ic:\C30\files source.c 
VMS [C30.filesjalt.c cpp30 -i[C30.files] source.c 
UNIX /C30/files/alt.c cpp30 -i/C30/files source.c 
MPW CS0TEtlestalt.c cpp30 -i:C30 :files source.c 


Note that the include filename is enclosed in double quotes. The preproces- 
sor first searches for alt .c in the current directory, because source.c is 
in the current directory. Then, the preprocessor searches the directory 
named with the —i option. 


2.8.1.3 Environment Variable 


An environment variable is a system symbol that you define and assign a 
string to. The preprocessor uses an environment variable named C_DIR to 
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VMS 


UNIX 
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name alternate directories that contain include files. The commands for as- 
signing the environment variable are: 
DOS: set C DIR= pathname;another pathname ... 
VMS: assign ”pathname;another pathname...” Cc_DIR 
UNIX: setenv C_DIR ”pathname,another pathname ...” 
MPW: set C DIR ’pathname;another: pathname...” 
export C_ DIR 


The pathnames are directories that contain include files. You can separate 
pathnames with a semicolon or with blanks. In C source, you can use the 
#include directive without specifying any path information; instead, you can 
specify the path information with C_DIR. 


Forexample, assume that a file called source.ccontains these statements: 


#include <alti.c> 
#include <alt2.c> 


The table below lists the complete pathnames for these files and shows how 
to invoke the preprocessor; select the row for your operating system. 


Pathname for altl.c Invocation Command 


and alt2.c 
e:\C30\files\altl.c |set C_DIR=c:\sys c:\exec\files 
e:\sys\alt2.c cpp30 -ic:\C30\files source.c 
[C30.filesjJaltl.c assign C DIR “{sys] [exec.files]” 
[sysJalt2.c cpp30 -i[C30.files] source.c 
/C30/files/altl.c | setenv C_DIR ”“/sys /exec/files 
/ygs/alt2.c cpp30 -i\C30\files source.c 
:C30 :files :altl.c set C DIR ” :sys :files ” 
:sys:alt2.c export C DIR 


cpp30 ~i:C30 :files source.c 


Note that the include filenames are enclosed in angle brackets. The prepro- 
cessor first searches for these files in the directories named with C_DIR and 
finds alt2.c. Then, the preprocessor searches in the directories named 
with the —i option and finds alti.c. 


The environment variable remains set until you reboot the system or reset 
the variable by entering: 


DOS: set C DIR= 
VMS: = deassign C DIR 
UNIX: setenv CDin 
MPW: unset C DIR 
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2.8.2 Parsing C Code 


The second step in compiling a TMS320C30 C program is to invoke the C 
parser. The parser reads the modified source file produced by the prepro- 
cessor, parses the file, checks the syntax, and produces an intermediate file 
that can be used as input for the code generator. (Note that the input file can 
also be a C source file that has not been preprocessed.) 


To invoke the parser as a standalone program, enter: 


cc30 is the command that invokes the parser. 


input file names the preprocessed C source file that the parser uses as 
input. If you don’t supply an extension, the parser assumes 
that the extension is .cpp. If you don’t specify an input file, the 
parser will prompt you for one. | 


output file names the intermediate file that the parser creates. If you 
don’t supply a filename for the output file, the parser uses the 
input filename with an exterision of ./f. 


options affect the way the parser processes the inputfile. Valid options 
include: 


—q suppresses the banner and status information. 


—Z tells the parser to retain the input file (the 
intermediate file created by the preprocessor). If you 
don’t specify —z, the parser deletes the . cppinputfile. 
(The parser never deletes files with the .c extension.) 


Most errors are fatal; that is, they prevent the parser from generating an in- 
termediate file and must be corrected before you can finish compiling a pro- 
gram. Some errors, however, merely produce warnings that hint of prob- 
lems but do not prevent the parser from producing an intermediate file. 


When the parser encounters function definitions, it prints a progress mes- 
sage that contains the name of the source file and the name of the function. 
Here is an example of a progress message: 


“filename.c”: => main 


This type of message shows how far the compiler has progressed in its ex- 
ecution and helps you to identify the locations of an error. You can use the 
—q option to suppress these messages. 


If the input file has an extension of . cpp, the parser deletes it upon comple- 
tion unless you use the —z option. If the input file has an extension other than 
.cpp, the parser does not delete it. 
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The intermediate file is a binary file; do not try to inspect or modify it in any 


way. 


2.8.3 Generating Assembly Language Code 
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The third step in compiling a TMS320C30 C program is to invoke the C code 
generator. As Figure 2—4 on page 2-16 shows, the code generator con- 
verts the intermediate file produced by the parser into an assembly lan- 
guage source file. You can modify this output file or use it as input for the 
TMS320C30 assembler. The code generator produces re-entrant relocat- 
able code, which, after assembling and linking, can be stored in ROM. 


To invoke the code generator as standalone, enter: 


cg30 
input file 


output file 


tempfile 


options 


is the command that invokes the code generator. 


names the intermediate file that the code generator uses as 
input. If you don’t supply an extension, the code generator as- 
sumes thatthe extension is ./f. lf you don’t specify an input file, 
the code generator will prompt you for one. 


names the assembly language source file that the code gen- 
erator creates. If you don’t supply a filename for the output file, 
the code generator uses the input filename with an extension 
of .asm. 


names a temporary file that the code generator creates and 
uses. The default filename for the temporary file is the input 
filename appended with an extension of .tmp. The code gen- 
erator deletes this file after using it. 


affect the way the code generator processes the input file. 
Valid options include: 


—a assumes variables are aliased. For more informa- 
tion, refer to Section 2.4 on page 2-9 


—b tells the compiler to generate code for the big 
memory model. 


—m enables the short multiply. For more information, 
refer to Section 2.4 on page 2-9. 
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—O 


—X 


—Z 
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normal optimization, even with debug. When you 
generate symbolic debugging information with the -g 
switch, the code generator disables certain optimiza- 
tions that inhibit debugging. You can use —mn to re- 
enable these optimizations and generate exactly the 
same code as without —g. 


tells the code generator to place symbolic debugging 
directives in the output file. See Appendix B of the 
TMS320C30 Assembly Language Tools User’s 
Guide for more information about these directives. 


suppresses the banner and status information. 


assumes variables are volatile. Variables are always 
read from memory each time they are accessed. For 
more information, refer to Section 2.4 on page 2-9 


avoids early silicon bugs. —x enables the code gener- 
ator to work around some of the known hardware 
bugs in early TMX320C30 devices. 


tells the code generator to retain the input file (the in- 
termediate file created by the parser). This option is 
useful for creating several output files with different 
options; for example, you might want to use the same 
intermediate file to create one file that contains sym- 
bolic debugging directives (—o option) and one that 
doesn’t. Note that if you do not specify the —z option, 
the code generator deletes the input (intermediate) 
file. 


2-23 


Linking a C Program 


SOORS RSS eR eee eeeeessessEE 


aE SESSESSBERESEN ES aPameeaasoeelawasasaseoaoanantoteee seeanavaesasososoneeseseveoaoaononabogeeeesasaraososnaasoneessesenasansesonnenesessasnsosesecnasaaaesesabenesesesaaaeaasoponoeesasaesaseatonveeenssstsassosonenebonessnsssesasosnsonononegenesstasassosonensnseoegessanansonsnareanegsnsaassoaeneeeeneanaesesanonosaconsasasaessasasbopeeenetssamaasssnsososonogasosassseseassosssounganene 


2.9 Linking aC Program 


The TMS320C30 C compiler and assembly language tools support modular 
programming by allowing you to compile and assemble individual modules 
and then link them together. To link compiled and assembled code, enter: 


ink30 is the command that invokes the linker. 


—c/—cr are options that tell the linker to use special conventions 
that are defined by the C environment. Note that when you 
use CL30 to link, CL30 passes —c to the linker automatical- 
ly. 


filenames are object files created by compiling and assembling C pro- 
grams. 


—oname.out names the output file. If you don’t use the —o option, the 
linker creates an output file with the default name of 
a.out. 


rts.lib rts.1lib Is an archive library that contains C runtime-sup- 
port functions. (The —| option tells the linker that a file is an 
object library.) The library is shipped with the C compiler. If 
you're linking C code, you must use rts.1ib. Whenever 
you specify a library as linker input, the linker includes and 
links only those library members that resolve undefined ref- 
erences. 7 


For example, you can link a C program consisting of modules progi, 
prog2, and prog3 (the output file is named prog. out): 

InksO +-@ prog. progZ prog3. -=-1l: rts.1i1b° 6 prog.out [au] 

The linker uses a default allocation algorithm to allocate your program into 


memory. You can use the MEMORY and SECTIONS linker directives to 
customize the allocation process. 


2.9.1 Runtime Initialization and Runtime Support 
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AllC programs must be linked with the boot . obj object module; this module 
contains code for the C boot routine. The boot . obj module is a member of 
the runtime-support object library, rts .1ib. To use the module, simply use 
—c or —cr and include the library in the link: 


Ink30 -c -l rts.lib.. 
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The linker automatically extracts boot .obj and links itin when you use the 
—C or —cr option. 


When aC program begins running, it must execute boot . obj first. The sym- 
bol c_intoo is the starting point in boot .ob3; if you use the —c or —cr 
option, then c_ int0o is automatically defined as the entry point for the pro- 
gram. If your program begins running from reset, you should set up the reset 
vector to generate abranchto c_int0oo so that the TMS320C30 executes 
boot .ob3 first. The boot . obj module contains code and data for initializing 
the runtime environment; the module performs the following tasks: 


Lk Sets up the system stack. 

Li Processes the runtime initialization table and autoinitializes global 
variables (in the ROM model). 

[4 Disables interrupts and calls main. 

La Calls exit when main returns. 


Chapter 5 describes additional runtime-support functions that are included 
in rts.1lib. If your program uses any of these functions, you must link 
rts.1lib with your object files. 


2.9.2 Sample Linker Command File 


Figure 2—5 shows a typical linker command file that can be used to link a 
C program. The command file in this example is named link. cmd. 


Figure 2-5. An Example of a Linker Command File 


[RRR KRRKKRKKKKKKKKKKKKKKKK KK KKK KKK KKK KKK KKKKKKKKKKKKKKK KK | 


7 * Linker command file link.cmd ais 
[RRR KKKKKKKKK KK KKK KKK KKK KKK KKK KKK KKKKKKK KK KKK KKK KKK KKK / 


ak ROM autoinitialization model 
-m example.map Create a map file 

-o example.out Output file name 

main.obj First C module 

sub.ob7j Second C module 

asm.obj Assembly language module 

=l rts.«ilib Runtime-support library 

-l matrix.lib Object library 


La The command file first lists several linker options: 
—c _ tells the linker to use the ROM model of autoinitialization. 


-—m _ tells the linker to create a map file; the map file in this example is 
named example.map. 


-o __ tellsthe linker to create an executable object module; the module 
in this example is named example. out. 
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La Next, the command file lists all the object files to be linked. This C pro- 
gram consists of two C modules, main.c and sub.c, which were com- 
piled and assembled to create two object files called main.ob3j and 
sub.obj. This example also links in an assembly language module 
called asm. ob}. 


One of these files must define the symbol main, because boot . obj calls 
main as the start of your C program. All of these object files are linked in. 


La Finally, the command file lists all the object libraries that the linker must 
search. (The libraries are specified with the —I linker option.) Because 
this is a C program, the runtime-support library rts.1ib must be in- 
cluded. This program uses several routines from an archive library 
called mat rix.1ib, so itis also named as linker input. Note that only the 
library members that resolve undefined references are linked in. 


To link the program using this command file, simply enter: 


1nk30 link.cmd [uj 


This example uses the default memory allocation described in Chapter 9 of 
the TMS320C30 Assembly Language Tools User’s Guide. \f you want to 
specify different MEMORY and SECTIONS definitions, refer to that user’s 
guide. 


2.9.3 Autoinitialization (RAM and ROM Models) 
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The C compiler produces tables of data for autoinitializing global variables. 
Section 4.10.1.1, page 4-31, discusses the format of these tables. These 
tables are in a named section called .cinit. The initialization tables can be 
used in either of two ways: 


La RAM Model (—-cr linker option) 


Global variables are initialized at load time. A loader copies the initial- 
ization data into the variables in the .bss section; thus, no runtime 
initialization is performed at boot time. This enhances performance by 
reducing boot time and saving memory used by the initialization tables. 


For more information about the RAM model, refer to Section 4.10.1.20n 
page 4-32. 
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Linking a C Program 


Cy ROM Model (—c linker option) 


Global variables are initialized at run time. The .cinit section is loaded 
into memory along with all the other sections. The linker defines a spe- 
cial symbol called cinit that points to the beginning of the tables in 
memory. When the program begins running, the C boot routine copies 
data from the tables into the specified variables in the .bss section. This 
allows initialization data to be stored in ROM and then copied to RAM 
each time the program is started. 


For more information about the ROM model, refer to Section 4.10.1.3 
on page 4-33. 


2.9.4 The-—c and -cr Linker Options 


The following list outlines what happens when you invoke the linker with the 
—C or —cr option. 


a 


The symbol _c_int0oo is defined as the program entry point; it identifies 
the beginning of the C boot routine in boot .ob3j. When you use —c or 
—Cr, c int00 is automatically referenced; this ensures that boot .ob3 
is automatically linked in from the runtime-support library rts.1lib. 


The .cinit output section is padded with a termination record so that the 
loader (RAM model) or the boot routine (ROM model) knows when to 
stop reading the initialization tables. 


In the RAM model (-cr option): 


m Thelinkersets the symbol cinit to—1. This indicates that the initial- 
ization tables are not in memory, so no initialization is performed at 
run time. 


m The STYP_COPY flag (010h) is set in the .cinit section header. 
STYP_COPY is the special attribute that tells the loader to perform 
autoinitialization directly and not to load the .cinit section into 
memory. The linker does not allocate space in memory for the .cinit 
section. 


In the ROM model (-c option), the linker defines the symbol cinit as 
the starting address of the .cinit section. The C boot routine uses this 
symbol as the starting point for autoinitialization. 
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2.10 Using the Archiver with C 
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An archive file (or library) is a partitioned file that contains complete files as 
members. The TMS320C30 archiver is a software utility that allows you to 
collect files into a single archive file. The archiver also allows you to manipu- 
late a library by adding members to it or by extracting, deleting, or replacing 
members. The TMS320C30 Assembly Language Tools User’s Guide con- 
tains complete instructions for using the archiver. 


After compiling and assembling multiple files, you can use the archiver to 
collect the object files into a library. You can specify an archive file as linker 
input. The linker is able to discern which files in a library resolve external ref- 
erences, and it links in only those library members that it needs. This is use- 
ful for creating a library of related functions; the linker links in only the func- 
tions that a program calls. The library rts.1ib is an example of an object 
library. 


You can also use the archiver to collect C source programs into a library. The 
C compiler cannot choose individual files from a library; you must extract 
them before compiling them. However, this can be useful for managing files 
and for transferring source files between systems. The library rts.src is 
an example of an archive file that contains source files. 


For more information about the archiver, see the TMS320C30 Assembly 
Language Tools User’s Guide. 
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Chapter 3 


TMS320C30 C Language 


The C language that the TMS320C30 C compiler supports is based on the 
Unix System V C language that is described by Kernighan and Ritchie, with 
several additions and enhancements to provide compatibility with ANSI C. 
The most significant differences are: 


Li The data type enum has been added. 


Ly A member of a structure can have the same name as a member of 
another structure (unique names aren't required). 


La Structures and unions can be passed as parameters to functions, re- 
turned from functions, and assigned directly. 


This chapter compares the two forms of C language and presents only the 
differences between them. The TMS320C30 C compiler supports standard 
Kernighan and Ritchie C except as noted. 


References to Kernighan and Ritchie’s C_Reference Manual (Appendix A 
of The C Programming Language) are used throughout this chapter. 


Topics in this chapter include: 
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3.1 Identifiers, Keywords, and Constants 


K&R 2.2 


K&R 2.3 


K&R 2.41 


K&R 2.43 


Identifiers 


Ci In TMS320C30 C, the first 31 characters of an identifier are 
significant (in K&R C, 8 characters are significant). This also applies 
to external names. 


La Case is significant; uppercase characters are different from lower- 
case characters in all TMS320C30 tools. This also applies to external 
names. 

Keywords 

TMS320C30 C reserves three additional keywords: 

asm 


void 
enum 


Integer Constants 


{4a ~All integer constants are of type int (signed, 32 bits long) unless they 


have an L or Usuffix. If the compiler encounters an invalid digit in a con- 
stant (such as an 8 or 9 in an octal constant), it issues a warning 
message. 


Lu You can append a letter suffix to an integer constant to specify its type: 


m Use Uas a suffix to declare an unsigned integer constant. 
m Use Las a suffix to declare a long integer constant. 
= Combine the suffixes to declare an unsigned long integer constant. 


Suffixes can be upper or lower case. 
La Here are some examples of integer constants: 


1234; /* int * / 

OxFFFFFFFFu; /* unsigned int a 

OL; /* long int * / 

077613LU; /* unsigned long int x / 
Character Constants 


In addition to the escape codes listed in K&R, the TMS320C30 C compiler 
recognizes the escape code \v in character and string constants as a 
vertical tab character (ASCII code 11). 


Added Type — Enumeration Constants 
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An enumeration constant is an additional type of integer constant that 
is not described by K&R. An identifier that is declared as an enumerator can 
be used in the same manner that an integer constant can be used. (For more 
information about enumerators, refer to Section 3.5 on page 3-7.) 
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K&R 2.5 


Identifiers, Keywords, and Constants 


String Constants 


Ch K&R C does not limit the length of string constants; however, 
TMS320C30 C limits the length of string constants to 255 bytes. 


(4 Any characters that follow an embedded null byte within a string 
constant are ignored; in other words, the first null byte terminates a 
string. 


This does not apply to strings used to initialize arrays of characters. 


La Identical string constants are stored as a single string, not as 
separate strings as in K&R C. 


This does not apply to strings used for autoinitialization of arrays of 
characters. 
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3.2 TMS320C30 C Data Types 


K&R 4.0 


K&R 4.0 


K&R 4.0 


Added Type and Equivalent Types 


a 


a 


ia 


The char data type is signed. A separate type, unsigned char, is also 
supported. 


char, short, long, and int are functionally equivalent types. Any of these 
types can be declared unsigned. 


The properties of enum types are identical to those of unsigned int. 


Added Types 


Cd 


An additional type, called void, can be used to declare a function that 
returns no value. The compiler checks that functions declared as void 
do not return values and that they are not used in expressions. Func- 
tions are the only type of objects that can be declared void. 


The compiler also supports a type that is a pointer to void (void*). An 
object of type void * can be converted to and from a pointer to an object 
of any other type without explicit conversions (casts). However, such a 
pointer cannot be used indirectly to access the object that it points to 
without a conversion. For example, 


void *p, *malloc(); 

char * Cz 

int if 

Madoc); /* Legal * / 

Cc; /* Legal, no cast needed */ 

&i; /* Legal, no cast needed */ 

malloc(); /* Legal, no cast needed * / 

kp; /* Illegal, dereferencing 
void pointer a | 

*(int *)p; /* Legal, dereferencing 
casted void pointer 27 


tot uot tl 


Pp 
Pp 
Pp 
C 
a 


#- 
ll 


Derived Types 


TMS320C30 C allows any type declaration to have up to six derived types. 
Constructions such as pointer to, array of, and function returning can be 
combined and applied a maximum of six times. 


For example: 
ane. (* “ambit y). 4) Os 
translates as: 


1) 
2) 
3) 


an array of 

arrays of 

pointers to 

functions returning 
pointers to 

functions returning integers 
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It has six derived types, which is the maximum allowed. 


Structures, unions, and enumerations are not considered derived types for 
the purposes of these limits. 


An additional constraint is that the derived type cannot contain more than 
three array derivations. Note that each dimension in a multidimensional 
array is a separate array derivation; thus, arrays are limited to three dimen- 
sions in any type definition. However, types can be combined using typedefs 
to produce any dimensioned array. 


For example, the following construction declares x as a four-dimensional 
array: 


typedef int dim2[{][]; 
dim2 x[][]; 


Table 3—1. Summary of TMS320C30 Data Types (K&R 2.6) 


Type Size 
char 8 bits, signed ASCII 
unsigned char 8 bits, ASCII 
short 16 bits 
unsigned short 16 bits 
int 32 bits 
unsigned int 32 bits 
long 32 bits 
unsigned long 32 bits 
pointers 32 bits 
float | 32 bits 
Range: +5.88 x 10(-89) through 
+1.70 x 1098 
double 64 bits 
Range: +1.11 x 10(-308) through 
+8.99 x 10308 
enum 1—32 bits 
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3.3. Object Alignment 


La All objects except bit fields are aligned on 32-bit (one word) boundaries. 
Bit fields are always unsigned and can be from 1 to 32 bits in length. Ad- 
jacent fields are packed into adjacent bits of a word, but they do not 
overlap words; if a field would overlap into the next word, the entire field 
is placed into the next word. (A bit field never crosses a word boundary.) 
Fields are packed as they are encountered; the least significant bits of 
a structure word are filled first. 


La When the compiler allocates space for a structure, it allocates as many 
words as are needed to hold all of the structure’s members. In an array 
of structures, each structure begins on a word boundary. 


3.4 Expressions 


Added type — Void Expressions 


A function of type void has no value (returns no value) and cannot be called 
in any way except as a separate statement or as the left operand of the 
comma operator. Functions can be declared or typecast as void. 


K&R 7.2 Unary Operators in Expressions 


The value yielded by the sizeof operator is calculated as the total number 
of bits used to store the object divided by 32. (32 is the number of bits ina 
character.) Sizeof can be legally applied to bit fields. If the result is not an 
integer, it is rounded up to the nearest integer. For example, 
Sizeof(int) == sizeof(short) == sizeof(char) == 


sizeof(long) == sizeof(float) == sizeof(double) == 1 


3-6 TMS320C30 C Language 


Declarations 
SSeS OU SS a a  S SO 


3.5 Declarations 


K&R 8.1 


K&R 8.2 


K&R 8.4 


K&R 10 


Register Variables 


La The TMS320C30 C compiler allows you to use up to eight register vari- 
ables in a function: 


m@ Two TMS320C30 registers (R4 and R5) are reserved for the first 
two integer register variables in a function. 


m Two registers (R6 and R7) are reserved for float or double register 
variables. 


m Four registers (AR4—AR7) are reserved for pointer register vari- 
ables. 


For more information about register variables, refer to Section 4.3, 
Register Conventions, on page 4-12. 


La Allinteger types (signed or unsigned), floats, doubles, and pointers, can 
be declared as registers. 


Type Specifiers in Declarations 


In addition to the type specifiers listed in K&R, objects can be declared with 
enum specifiers. 


TMS320C30 C allows more type name combinations than K&R C allows. 
The adjectives jong and short can be used with or without the word int; the 
meaning is the same in either case. The word unsigned can be used in con- 
junction with any integer type or alone; if alone, intis implied. Long float is 
asynonym for double. Otherwise, only one type specifier is allowed in a dec- 
laration. 


Passing/Returning Structures to/from Functions 


Contrary to K&R, TMS320C30 C allows functions to return structures and 
unions. 


Structures and unions can be used as parameters to functions, can be di- 
rectly assigned, and can be returned from functions. 


External Definitions 


Formal parameters to a function can be declared as type struct, union, or 
enum (in addition to the normal function declarations) because TMS320030 
C allows these types of objects to be passed to functions. 


K&R 8.5, K&R 14.1 Structure and Union Declarations 


Bit fields are limited to a maximum size of 32 bits. Any integer type can be 
declared as afield. Fields are always treated as unsigned, regardless of def- 
inition. 
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K&R states that structure and union member names must be mutually dis- 
tinct. In TMS320C30 C, members of different structures or unions can 
have the same name. However, this requires that references to the mem- 
ber be fully qualified through all levels of nesting. | 


TMS320C30 C allows assignment to and from structures, passing struc- 
tures as parameters, and returning structures from functions. 


K&R states that the compiler determines the type of structure reference by 
the member name. Because TMS320C30 C does not require member 
names to be unique, this statement does not apply. All structure references 
must be fully qualified as members of the structure or union in which they 
were declared. 


Added Type — Enumeration Declarations 
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Enumerations allow the use of named integer constants in TMS320C30 C. 
The syntax of an enumeration declaration is similar to that of a structure or 
union. The keyword enum is substituted for struct or union, and a list of 
enumerators is substituted for the list of members. 


Enumeration declarations have a tag, as do structure and union declara- 
tions. This tag can be used in future declarations without repeating the entire 
declaration. 


The list of enumerators is simply a comma-separated list of identifiers. Each 
identifier can be followed by an equal sign and an integer constant. If no enu- 
merator is followed by an = sign and a value, then the first enumerator is 
assigned the value 0, the next is 1, the next is 2, etc. An identifier with an 
assigned value assumes that value, and subsequent enumerators continue 
counting by one from there. The assigned value can be negative, but count- 
ing still continues by positive one. 


Unlike structure and union members, enumerators share their name space 
with ordinary variables and, therefore, must not conflict with variables or 
other enumerators in the same scope. 


Enumerators can appear wherever integer constants are required and, 
therefore, can be used in arithmetic expressions, case expressions, etc. In 
addition, explicit integer expressions can be assigned to variables of type 
enum. The compiler does no range checking to insure the value will fit in the 
enumeration field. The compiler does, however, issue a warning message 
if an enumerator of one type is assigned to a variable of another. 
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Here’s an example of an enumeration declaration: 


enum 


color { 

red, 

blue, 

green = 10, 
orange, 

purple = -2, 
cyan } x; 


This statement declares x as a variable of type enum. The enumerators and 
their assigned values are: 


red: 0 
blue: 1 
green: 10 
orange: 11 
purple: -—2 
cyan: —1 


32 bits are allocated for the variable x. Legal operations on these enumera- 
tors include: 


x 


mM Be MM 


blue; 
blue + red; 
100; 
red; /* assume i is an int */ 
1 + cyan; 
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3.6 Initialization of Static and Global Variables 


K&R 8.6 


Animportant difference between K&R C and TMS320C30 C is that external 
and static variables are not preinitialized to zero unless the program ex- 
plicitly does so or unless it is specified by the linker. 


lf a program requires external and static variables to be preinitialized, you 
can use the linker to accomplish this. In the linker control file, use a fill value 
of 0 in the .bss section: 


SECTIONS { 
-oss { } = 0x00; 
} 


3.7 Lexical Scope Rules 


K&R 11.1 
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The lexical scope rules stated in K&R apply to TMS320C30 C also, except 
that structures and unions each have distinct name spaces for their mem- 
bers. In addition, the name space of both enumeration variables and enu- 
meration constants is the same as for ordinary variables. 
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3.8 asm Statement 
Additional Statement 


TMS320C30 C has another statement not mentioned in K&R: the asm 
statement. The compiler copies asm statements from the C source directly 
into the assembly language output file. The syntax of the asm statement is: 


asm("assembler text’); 


The assembler text must be enclosed in double quotes. All the usual charac- 
ter string escape codes retain their definitions. The assembler text is copied 
directly to the assembler source file. Note that the assembler source state- 
ment must begin with a label, a blank, or a comment indicator (asterisk or 
semicolon). 


Each asm statement injects one line of assembly language into the compiler 
output. A series of asm commands places the statements sequentially into 
the output with no intervening code. 


Asm statements do not follow the syntactic restrictions of normal statements 
and can appear anywhere in the C source, even outside blocks. However, 
they are ignored when they appear in a list of declarations. 


SR a aaa a a a I | 


Note: 


Be extremely careful not to disrupt the C environment with asm commands. 
The compiler does not check the inserted instructions. Inserting jumps and 
labels into C code can cause unpredictable results in variables manipulated 
in or around the inserted code. The asm command is provided so you can 
access features of the hardware, which by definition C is unable to access. 
Specifically, do not use this command to change the value of a C variable; 
however, you can use it safely to read the current value of a variable. 
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The asm command is very useful in the context of register variables. A regis- 
ter variable is a variable in a C program that is declared to reside in a ma- 
chine register. The TMS320C30 C compiler allows up to 8 machine registers 
to be allocated to register variables. These 8 registers, combined with the 
asm command, provide a means of manipulating data independently of the 
C environment. 
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3.49 TMS320C30 C Language 


Chapter 4 


Runtime Environment 


This chapter describes the TMS320C30 C runtime environment. To ensure 
successful execution of C programs, it is critical that all runtime code main- 
tain this environment. If you write assembly language functions that 
interface to C code, follow the guidelines in this section. 


Topics in this chapter include: 
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4.1 


Memory Model 


The C compiler treats memory as a single linear block of memory that is par- 
titioned into subblocks of code and data. Each block of code or data that a 
C program generates will be placed in its own contiguous space in memory. 
The compiler assumes thatthe full 24-bit address space is available in target 
memory. 


Note that the linker, not the compiler, defines the memory map and allo- 
cates code and data into target memory. The compiler assumes nothing 
about the types of memory that are available, about any locations that are 
not available (holes), or about any locations that are reserved for I/O or con- 
trol purposes. The compiler produces relocatable code, which allows the 
linker to allocate code and data into the appropriate memory spaces. For 
example, you can use the linker to allocate global variables into fast internal 
RAM, or to allocate executable code into internal ROM. 


4.1.1 Sections 
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The compiler produces five relocatable blocks of code and data; these 
blocks, called sections, can be allocated into memory in a variety of ways 
to conform to a variety of system configurations. For more information about 
sections, read Chapter 3, Introduction to Common Object File Format, of the 
TMS320C30 Assembly Language Tools User’s Guide. 


There are two basic types of sections: 


La Initialized sections contain data tables or executable code. The C 
compiler creates two initialized sections, .text and .cinit. 


m The .text section is an initialized section that contains all the 
executable code as well as string literals. 


Mm The .cinit section is an initialized section that contains tables for 
initializing variables and constants. 


Ld Uninitialized sections reserve space in memory (usually in RAM). A 
program can use this space at run time for creating and storing vari- 
ables. The C compiler creates three uninitialized sections, .bss, .stack, 
and .sysmem. 


m The .bss section is an uninitialized section. It reserves space for 
global and static variables, and in the small model (described in 
section 4.1.2), it reserves space for tables of long immediate con- 
stants. At program startup time, the C boot routine copies data out 
of the .cinit section (which may be in ROM) and stores it in .bss. 


m The .stack section is an uninitialized section. It allocates memory 
for the system stack, which is used to pass arguments to functions 
and to allocate local variables. 
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m The .sysmem section is an uninitialized section. It allocates 
memory for use by the dynamic memory functions malloc, calloc, 
and realloc. IfaC program does not use these functions, then the 
compiler does not create the .sysmem section. 


Note that the assembler creates an additional section called .data; the C 
compiler does not use this section. The linker takes the individual sections 
from different modules and combines sections with the same name to create 
six output sections. The complete program is made up of these five output 
sections, plus the assembler’s .data section. You can place these output 
sections anywhere in the address space, as needed, to meet system re- 
quirements. The .text, .cinit, and .data sections are usually linked into either 
ROM or RAM. The .bss, .stack, and .sysmem sections should be linked into 
some type of RAM. 


For more information about allocating sections into memory, refer to 
Chapter 9, Linker Description, in the TMS320C30 Assembly Language 
Tools User’s Guide. 


4.1.2 Big and Small Memory Models 


The compiler supports two memory models that affect the treatment of the 
.Oss section: 


[4 The small memory model, which is the default model, requires the 
entire .bss section to fit in a single 64K memory page (65,536 words). 
This means that the total space for all static and global data in the pro- 
gram must be less than 64K and that the .bss section cannot span any 
64K address boundaries. The compiler sets the Data Page Pointer reg- 
ister (DP) during runtime initialization to point to the beginning of .bss. 
Then, the compiler can access all objects in .bss (global and static vari- 
ables, plus constant tables) with direct addressing (@symbol) without 
modifying the DP. 


La The big memory model does not restrict the size of .bss; unlimited 
space is available for global and static data. However, when the 
compiler accesses any global or static object that is stored in .bss, it 
must first ensure that the DP correctly identifies the memory page 
where the object is stored. To accomplish this, the compiler must explic- 
itly set the DP register (using an LDP instruction) each time a global or 
static object is accessed. This task incurs one extra instruction word (for 
the LDP instruction) and three additional cycles (one to execute the LDP 
and a two-cycle pipeline delay if the object is accessed by the next 
instruction). 
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Here’s an example of assembly language code that uses the LDP in- 
struction to set up the DP register before accessing a global variable. 


xxx Assume that x is a global variable *** 
LDP x ; 1 extra word, 1 cycle 


LDI @ x,RO ; 3 cycles (2 pipeline delays) 
To use the big model, invoke the compiler with the —mb option; for more 
information, refer to Section 2.4 on page 2-6. 
Neither model restricts the size of the .text or .cinit sections. 


Both models restrict the size of a single function to 32K (82768 words of 
code) or less; this allows the compiler to generate relative conditional jumps 
over the entire range of a function. 
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Note: 


Be sure all code in the system is compiled under the same model. 
Mixed-model code will not run. The runtime-support library that is provided 
with the compiler (rts .1ib) is compiled with the small model. To use the 
library under the big model, you must: 


1) €xtract all the source files from the source archive rts.src. 


2) Recompile these extracted files; be sure to invoke the code generator 
with the —b option. 


3) Archive the object files into a new library. 
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Neither model restricts the size of the dynamic memory area inthe .sysmem 
section because dynamically allocated objects are accessed with indirect, 
rather than direct, addressing. Thus, if you have large data objects, it is ad- 
vantageous to allocate them dynamically rather than declare them as static 
or global variables; for more information, refer to Section 4.1.4 on page 
4-6. 


Under the small model, be careful when linking the .bss section; it must be 
less than 64K words and it cannot span any 64K page boundaries. Neither 
the compiler nor the linker checks for restrictions on .bss against the model 
used. If you choose to use the small model and your code does not conform 
to small-model restrictions, the code will not run. If you want to verify that 
the .bss section is fully contained within a 64K memory page, check the link 
map after linking. 
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4.1.3 C System Stack 
The C compiler uses a stack to: 
14 Allocate local variables, 
[i Pass arguments to functions, and 
Lh Save temporary results. 
The compiler uses two registers to manage the stack: 
SP _ is the stack pointer; it marks the top of the stack. 


AR3 is the frame pointer (FP); it points to the beginning of the current 
local frame. (A local frame is an area on the stack that is used for stor- 
ing arguments and local variables.) Each function invocation causes 
a new local frame to be created at the top of the stack. 


The C environment automatically manipulates these registers when a C 
function is called. If you interface assembly language routines to C, be sure 
to use the registers in the same way that the C compiler uses them. 


The C initialization module, boot .asm, allocates memory for the stack in an 
uninitialized, named section called .stack. This module also defines a con- 
stant named stack sz1ze that determines the size of the stack. The default 
stack size is 400h (1K words); this size allows the stack to fit into one of the 
on-chip RAM blocks. You can change the amount of memory that is re- 
served for the stack by following these steps: 


1) Extract boot .asm from the source library rts.src. 


2) Edit boot .asm; change the value of the constant sTack_s1zs to the de- 
sired stack size. 


3) Reassemble boot .asmand replace the ean object file, boot .obj, 
in the object library rts.1ib. . 


4) Replace the copy of boot .asm that’s in rts.src with the new, edited 
version. 


At system initialization, the SP is set to a designated address for the bot- 
tom-of-stack. This address is the first location in the .stack section. Thus, 
the actual position of the stack is determined at link time, because the 
position of the stack depends on where the .stack section is allocated. If you ~ 
allocate the stack as the last section in memory (highest address), the stack 
has unlimited space in which to grow (within the limits of system memory). 
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Note: 


The compiler provides no means to check for stack overflow during compi- 
lation or at run time. If the stack overflows, your system will probably crash. 
Be sure that you allow enough space for the stack to grow; either set 
STACK SIZE to an appropriate amount or allocate the .stack section last. 
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4.1.4 Dynamic Memory Allocation 
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The runtime-support library supplied with the compiler contains several 
functions (Such aS malloc, calloc, and realloc) that allow you to dynami- 
cally allocate memory for variables at run time. This is accomplished by 
declaring alarge memory pool, or heap, and then using the functions to allo- 
cate memory from the heap. Dynamic allocation is not a standard part of the 
C language; it is provided by standard runtime-support functions. 


An assembly language module called sysmem.asm defines this memory 
pool as an uninitialized, named section called .sysmem. The module also 
definesaconstantnamed — sysmemM s1zethatdetermines the size ofthe 


memory pool; the default size is 800h (2K words). You can change the size 
of the memory pool by following these steps: 


1) Extract sysmem.asm from the source library rts.src. 


2) Edit sysmem.asm; change the value of the constant | SYSMEM SIZE 
to the desired memory pool size. 


3) Reassemble sysmem.asm and replace the resulting object file, 
sysmem.obj, in the object library rts.1ib. 


4) Replace the copy of sysmem.asm that’s in rts. src with the new, edited 
version. 


Dynamically allocated objects are not addressed directly (they are always 
accessed with pointers), and the memory pool is in a separate section; 
therefore, the dynamic memory pool can have an unlimited size, even inthe 
small memory model. The size of the pool does not affect the 64K limit on 
global and static variables. This allows you to use the more efficient small 
memory model even if you declare large data objects. To conserve space 
in .bss, you can allocate large arrays from the heap instead of declaring 
them as global or static. For example, instead of a declaration such as: 


struct big table[10000]; 
use a pointer, and call the malloc function: 


struct big *table; 
table = (struct big *)malloc (10000 * sizeof (struct big)); 
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Note: 


If you don’t use dynamic allocation—that is, if you don’t use calloc, 
malloc, and similar functions—then it is not necessary to allocate the .sys- 
mem section at link time. 
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4.1.5 RAM and ROM Models 


The C compiler produces code that is suitable for use as firmware in a 
ROM-based system. In such a system, the initialization tables in the .cinit 
section are stored in ROM. At system initialization time, the C boot routine 
copies data from these tables (in ROM) to the initialized variables in .bss (in 
RAM). 


In situations where a program is loaded directly from an object file into 
memory and then run, you can avoid having the .cinit section occupy space 
in memory. Your loader can read the initialization tables directly from the ob- 
ject file (instead of from ROM) and perform the initialization directly at load 
time (instead of at run time). You can specify this to the linker by using the 
—cr linker option. 


For more information about autoinitialization, refer to Section 4.10 on page 
4-30. 
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4.2 Object Representation 


4.2.1 Storage of Data Types 


Lk All basic types are 32-bits wide and stored in individual words of 
memory. No packing is performed, except for bit fields, which are 
packed into words. Bit fields are allocated from the LSB to the MSB in 
the order in which they are declared. 


La No object has any type of alignment requirement; any object can be 
stored on any 32-bit word boundary. Objects that are members of struc- 
tures or arrays are stored just as they are individually. Members are not 
packed into structures or arrays (unless the members are bit fields). 


La The integral types char, short, int, and long are all equivalent, as are 
their unsigned counterparts. Objects of type enum are also represented 
in 32-bit words. 


4 The float and double types are equivalent; both types specify objects 


represented in the TMS320C30’s 32-bit floating-point format. 


4.2.2 Long Immediate Values 


The TMS320C30 instruction set has no immediate operands that are longer 
than 16 bits. The compiler occasionally needs to use constants that are too 
long to be immediate operands. This occurs with signed integer constants 
that have more than 15 significant non-sign bits, with unsigned integers that 
have more than 16 significant bits, or with floating-point constants that have 
more than 11 significant non-sign bits in the mantissa. The compiler uses 
the .word and .float assembler directives to build atable in memory that con- 
tains allsuch constants. Constants in the table are then accessed like global 
variables, using direct addressing. Section 4.2.5, page 4-10, describes the 
structure of the constant table. 


4.2.3 Addressing Global Variables 
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The compiler generates the addresses of global or static symbols for index- 
ing arrays or manipulating pointers. Because these addresses may be up 
to 24 bits wide, and immediate operands are limited to 16 bits, these ad- 
dresses are treated like long constants as described in Section 4.2.2. The 
compiler generates addresses into the constant table using the .word as- 
sembler directive. Section 4.2.5, page 4-10, describes the structure of the 
constant table. 
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4.2.4 Character String Constants 


In C, a character string constant can be used in one of two ways: 


Ca 


It can initialize an array of characters; for example: 
char s[] = “abc”; 


When astring is used as an initializer, itis simply treated as an initialized 
array; each character is a separate initializer. For more information 
about autoinitialization, refer to Section 4.10 on page 4-30. 


It can be used as a pointer; for example: 
princL (“abc”) + 


When astring is used as a pointer, the string itself is defined in the .text 
section using the .byte assembler directive, along with a unique label 
that points to the string; the terminating 0 byte is included. For example, 
the following line defines the string abc, along with the terminating byte; 
the label s.5 points to the string: 


SL5 .byte “abc”,0 


String labels have the form SLn, where nis a number assigned by the 
compiler, beginning with 0 and increasing by 1 for each defined string. 
All strings used in a source module are defined at the end of the com- 
piled assembly language module. 


The label SLnrepresents the address of the string constant (a pointer to 
the string). Like all addresses of static objects, this address must be 
stored in the constant table in order to be accessed. Thus, in addition to 
storing the string itself in the .text section, the compiler uses the follow- 
ing directive statement to store the string’s address in the constant 
table: 


-word SbLn 


If the same string is used more than once within a source module, the 
string will not be duplicated in memory. All uses of an identical string 
constant share a single definition of the string. 


Oe 
Note: 


Each source module can have a maximum of 400 unique string constants; 
the code generator aboris with an error message if this limit is exceeded. 
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Because strings are stored in .text (possibly ROM) and shared, it is bad 
practice for a program to modify a string constant. The following code is an 
example of incorrect string use: 


a[1l] = ‘x’; /* Incorrect! */ 


4.2.5 The Constant Table 


The constant table contains definitions of all the objects that the compiler 
must access, but are too wide to be used as immediate operands. Such ob- 
jects include: 


La Integer constants that are wider than 16 bits. 


La Floating-point constants that have exponents larger than 4 bits or man- 
tissas larger than 11. 


14 Addresses of global variables. 
Ck Addresses of string constants. 


The constant table is simply a block of memory that contains all such 
objects. The compiler builds the constant table at the end of the source mod- 
ule by using the .word and .float assembler directives. Each entry in the table 
occupies one word. The label const points to the beginning of the table. For 


example: 

CONST: .word 011223344h 732 bit constant 
-float 3.1459265 ;floating-point constant 
.word _globvar ;address of global 
-word SL23 ;address of string 


Objects in the table are accessed with direct addressing; for example: 
LDI @CONST+offset, RO 


In this example, offset is the index into the constant table of the required 
object. As with string constants, identical constants used within a source 
module share a single entry in the table. 


In the big memory model, the constant table is built in the .text section (and 
is not copied into RAM). The compiler must insure that the DP register is cor- 
rectly loaded before accessing an object in the table, just as with accessing 
global variables. This requires an LDP instruction before each access to the 
constant table. 


The small model, however, avoids the overhead of loading DP by requiring 
that all directly addressable objects, including all global variables as well as 
the constant table, are stored in the same memory page. Of course, global 
variables must be stored in RAM. For the code to be ROM-able, the constant 
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table must be in ROM. In order to get them on the same page, the boot rou- 
tine must copy the constant table from permanent storage in ROM to the 
global page in RAM. The compiler accomplishes this by placing the data for 
the constant table in the .cinit section and allocating space for the table itself 
in .bss. Thus, the table is automatically built into RAM through the autoinitial- 
ization process. 


As with all autoinitialization, you can avoid the extra use of memory required 
for the .cinit section by using the —cr linker option and using a smart loader 
to perform the initialization directly from the object file. For more information 
about autoinitialization, refer to Section 4.10 on page 4-30. 
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Note: 


1) The total size of the constant table in one module is limited to 1000 en- 
tries. If this limit is exceeded, the code generator aborts with an error 
message. 


2) Note that the small memory model restricts the total size of the global 
data page, including the constant tables, to 64K words. 
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4.3 Register Conventions 


Strict conventions associate specific registers with specific operations in the 
C environment. If you plan to interface assembly language routines to a C 
program, you must follow these register conventions. 


The C compiler uses the following registers: 


Table 4—1. List of the Registers the Compiler Uses 


Register Description 
RO Integer and floating-point expression register, also, scalar return 
values 
R1 Integer and floating-point expression register 
R2 Integer and floating-point expression register 
R3 Integer and floating-point expression register 
R4 Integer register variable 
R5 Integer register variable 
R6 Floating-point register variable 
R7 Floating-point register variable 
ARO Pointer expression register 
AR1 Pointer expression register 
AR2 Pointer expression register 
AR3 Frame pointer (FP) 
AR4 Pointer register variable 
AR5 Pointer register variable 
AR6 Pointer register variable 
AR7 Pointer register variable 
IRO Used for extended addressing on local frame 
IR1 Used for extended addressing on local frame 
SP Stack pointer 


4.3.1 Expression Analysis Registers 


The compiler uses registers RO—R3 and ARO—AR2 to evaluate expres- 
sions and store temporary results. The compiler keeps track of the current 
contents of each register and attempts to allocate registers for expressions 
in a way that preserves useful contents in the registers whenever possible. 
This allows the compiler to reuse register data and take advantage of the 
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TMS320C30’s efficient register addressing modes and to avoid unneces- 
sary accesses of variables and constants. 


When a function is called, the compiler forgets the contents of the expres- 
sion registers. The contents of any register that is being used for temporary 
storage is saved off to the local frame before the function is called. This pre- 
vents the called function from ever having to save and restore expression 
registers. 


If the compiler needs another register for an expression evaluation, a regis- 
ter that is being used for temporary storage can be saved on the local frame 
and used for the expression analysis. Typical expressions seldom require 
more than four expression registers. 


4.3.2 Return Values 


When a value of any scalar type (integer, pointer, or floating-point) is 
returned from a function, the value is placed in register RO when the function 
returns. 


4.3.3. Register Variables 


Specific registers are reserved for variables that are declared with the regis- 
ter storage class specifier. The register designation tells the compiler to 
store the associated variable in a register if possible, for efficient access. 
Register storage can be specified for any type of automatic variables, both 
function arguments and local variables. There are several registers for each 
type of register variable: 


Register Description 
R4, R5 are used for integer register variables. 
R6, R7 are used for floating-point register variables. 


AR4—AR7 | _ are used for pointer register variables. 


These registers are allocated in the order that they are declared; for exam- 
ple, the first integer variable declared as register is assigned to R4, and the 
second Is assigned to R5. If a function declares more register variables than 
the number of registers that are available for that type, the excess variables 
are treated as automatic variables. 


Using register variables can significantly increase the efficiency of a func- 
tion, especially when values are frequently assigned to a particular variable 
(vac = ...). 


Any function that uses register variables must save the contents of each 
register used on entrance to the function and restore them on exit. This 
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ensures that a called function does not disrupt the register variables of the 
calling function. 


Unused register variables can be freely manipulated using inline assembly 
language. 
4.3.4 Other Registers 


C4 The stack pointer (SP) and frame pointer (AR3) are used to manage the 
local frame. 


La The page pointer (DP) is used to access global and static variables. 
Called functions must preserve the values in these registers. 


Lu Index registers IRO and IR1 are used for indirect addressing when an 
offset of more than 8 bits (£255) is required. They are treated like ex- 
pression registers and need not be saved by called functions. 


La The block-repeat registers (RS, RE, and RC) are used to copy struc- 
tures. They need not be saved by called functions. 
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4.4 Function Structure and Calling Conventions 


The C compiler imposes a strict set of rules on function calls. Except for 
special runtime-support functions, any function that calls or is called by aC 
function must follow these rules. Failure to adhere to these rules can disrupt 
the C environment and cause the program to fail. 


Figure 4—1 illustrates atypical function call. In this example, parameters are 
passed to the function and the function uses local variables. 


Figure 4—1. Stack Use During a Function Call 
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Responsibilities of a Calling Function 


A function performs the following tasks when it calls another function. 


1) Thecaller pushes the arguments on the stack in reverse order (the right- 


most declared argument is pushed first and the leftmost is pushed last). 
This places the leftmost argument at the top of the stack when the 
function is called. 


The caller calls the function. 


When the called function is complete, the caller pops the arguments off 


the stack with the following instruction: 
SUBI n,SP 


nis the number of argument words that were pushed. 
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4.4.2 Responsibilities of a Called Function 


A called function must perform the following tasks. 


1) 


If the called function modifies any of the following registers, it must save 
them on the stack. 


Save as integers Save as floating-point 
R4 R5  AR4 | R6 
AR5 AR6 AR7 R7 
FP 


The called function may modify any other registers without saving them. 
lt executes the code for the function. 
It restores all saved registers. 


If the function returns an integer, pointer, or float, it places the return 
value in RO. If the function returns a structure, refer to Section 4.4.5 on 
page 4-17. 


4.4.3 Setting Up the Local Frame 


Called C functions perform additional actions in order to manage the local 
frame. Note that if the function has no local variables, and no need for local 
temporary storage, these actions are not taken. 


1) 


2) 


The called function sets up the local frame; this is the first action taken 
by the called function. The local frame is allocated as follows: 


a) The old frame pointer is saved on the stack. 
b) The new frame pointer is set to the current SP. 
c) The frame is allocated by adding its size to the SP. 


Before returning, the called function deallocates the frame by subtract- 
ing its size from SP and restores the old FP by popping it. 


4.4.4 Accessing Arguments and Local Variables 


A function accesses its arguments and local variables indirectly through the 
FP, which always points to the the bottom of the local frame. Because the 
FP actually points to the old FP, the first local variable is addressed as 
*+FP (1). Other local variables are addressed with increasing offsets, up to 
a maximum of 255. Local objects with offsets larger than 255 are accessed 
by first loading their offset into an index register (IRn) and addressing them 
aS *+FP (IRM). ms 
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Arguments are addressed in a similar way, but with negative offsets from 
the FP. The return address is stored at the location directly below the FP, 
so the first argument is addressed as *-Fp (2). Other arguments are ad- 
dressed with increasing offsets, up to a maximum of 255 words. The IR 
registers are also used to access arguments with offsets larger than 255. 


er ne ee 


Note: 


It is best to avoid using locals and arguments with offsets larger than 255 
words. The sequence used to access such variables is: 


LDI offset, IRn 
A+EP (IRn), 


This sequence incurs one additional instruction and three additional clock 
cycles each time it is used. If you must use a larger local frame, try to put 
the most frequently used variables within the first 255 words of the frame. 
Ferrera eninge aia al eel 


4.4.5 Returning Structures from Functions 


A special convention applies to functions that return structures. The caller 
allocates space for the structure and then passes the address of the return 
space to the called function in register ARO. To return a structure, the called 
function then copies the structure to the memory block that ARO points to. 


In this way, the caller can be “smart” about telling the called function where 
to return the structure. For example, in the statement s = £(), where sis 
a structure and ¢ is a function that returns a structure, the caller can simply 
place the address of s in ARO and call £. Function £ then copies the return 
structure directly into s, performing the assignment automatically. 


If the caller does not use the return value, ARO is set to 0. This directs the 
called function not to copy the return structure. 


You must be careful to properly declare functions that return structures both 
at the point where they are called (so the caller properly sets up ARO) and 
where they are defined (so the function knows to copy the result). 


Interfacing C with Assembly Language 


4.5 


4.5.1 
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Interfacing C with Assembly Language 
There are three ways to use assembly language in conjunction with C code: 


Ca 


Ca 


La 


Use separate modules of assembled code and link them with compiled 
C modules (see Section 4.5.1). This is the most versatile method. 


Use inline assembly language that is imbedded directly in the C source 
(see Section 4.5.2, page 4-22). 


Modify the assembly language code that the compiler produces (see 
Section 4.5.3, page 4-22). 


Assembly Language Modules 


Interfacing with assembly language functions is straightforward if you follow 
the calling conventions defined in Section 4.4 and the register conventions 
defined in Section 4.3. C code can access variables and call functions that 
are defined in assembly language, and assembly code can access C vari- 
ables and call C functions. 


Follow these guidelines to interface assembly language and C: 


1) 


2) 


All functions, whether they are written in C or assembly language, must 
follow the conventions outlined in Section 4.4, page 4-15). 


You must preserve any dedicated registers that are modified by a func- 
tion; dedicated registers include: 


Dedicated Registers 
R4 R5 R6 R7 
AR4 AR5 AR6 AR7 
SP FP (AR3) 


All registers are saved as integers except R6 and R7, which are saved 
as floating-point values. Note that if the SP is used normally, it does not 
need to be explicitly preserved. In other words, the assembly function is 
free to use the stack as long as anything that is pushed is popped back 
off before the function returns (thus preserving SP). 


All other registers (such as expression registers, index registers, status 
registers, and block repeat registers) are not dedicated and can be used 
freely without first being saved. 


Interrupt routines must save all the registers they use. Expression reg- 
isters RO—R3 must be saved as complete 40-bit values, because they 
may contain either integers or floating-point values when the interrupt 
occurs. For more information about interrupt handling, refer to Section 
4.6 on page 4-23. 
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4) When calling a C function from assembly language, push any argu- 
ments on the stack in reverse order. Pop them off after calling the func- 
tion. When calling C functions, remember that only the dedicated regis- 
ters listed above are preserved. C functions can change the contents 
of any other register. 


5) Functions must return values correctly according to their C declara- 
tions. Integers, pointers, and floating-point values are returned in 
register RO, and structures are returned as described in Section 4.4.5 
on page 4-17. 


6) Noassembly module should use the .cinit section for any purpose other 
than autoinitialization of global variables. The C startup routine in 
boot .asmassumes that the .cinit section consists entirely of initializa- 
tion tables. Disrupting the tables by putting other information in .cinitcan 
Cause unpredictable results. 


7) Thecompiler appends an underscore (_) to the beginning of all identifi- 
ers. In assembly language modules, you must use a prefix of _ for all 
objects that are to be accessible from C. For example, aC object named 
xis called x in assembly. For identifiers that are to be used only in an 
assembly language module or modules, any name that does not begin 
with a leading underscore may be safely used without conflicting with 
a C identifier. 


8) Any object or function declared in assembly that is to be accessed or 
called from C must be declared with the .global directive in the assem- 
bler. This defines the symbol as external and allows the linker to resolve 
references to it. 


Likewise, to access a C function or object from assembly, declare the C 
object with .global. This creates an undefined external reference that 
the linker will resolve. 


4.5.1.1 An Example of an Assembly Language Function 


The example in Section 4.2 illustrates a C function called main, which calls 
an assembly language function called asmfunc. The asmfunc function takes 
its single argument, adds it to the C global variable called gvar, and returns 
the result. 
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Figure 4-2. An Assembly Language Function 


(a) C program 


extern int asmfunc(); /* declare external asm function */ 
int gvar; /* define global variable x]; 


main () 


{ 


nt 4 aes 


asmfunc (i); /* call function normally 


AR3 ; FP is AR3 
_asmfunc ; Declare external function 
_gvar ; Declare external variable 


FP ; Save old FP 

SP,FP ; Point to top of stack 

*-—FP (2) ,RO ; Load argument into RO 

_gvar ; Set DP to page of gvar 
(BIG MODEL ONLY) 

@ gvar,RO ; Add gvar to argument in RO 

FP ; Restore FP 


In the C program in Figure 4—2, the ext ern declaration of asmfunc is option- 
al because the function returns an int. Like C functions, assembly functions 
need be declared only if they return non-integers. 


In the assembly language code in Figure 4—2, note the underscores on all 
the C symbol names. Note also that the DP needs to be set only when ac- 
cessing global variables in the big model. For the small model, the LDP 
instruction that loads the page pointer can be omitted. 


4.5.1.2 Defining Variables in Assembly Language 


lt is sometimes useful for a C program to access variables that are defined 
in assembly language. Accessing uninitialized variables from the .bss sec- 
tion is straightforward: 


[4 Use the .bss directive to define the variable. 

Lu Use the .global directive to make the definition external. 

La Remember to precede the name with an underscore. 

Ly In C, declare the variable as extern and access it normally. 
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Interfacing C with Assembly Language 


Figure 4—3 shows an example for accessing a variable defined in .bss. 


Figure 4-3. Accessing a Variable Defined in .bss from C 


(a) Assembly Language Program 


; Note the use of underscores 
; in the following lines 

-bss vary, L ; Define the variable 

-global var > Declare it as external 


(b) C Program 
extern int var; /* Bxternal variable */ 
var = 1; /* Use the variable */ 


If a variable is not defined in the .bss section, it is more difficult to access 
itfrom C. Acommon situation is a lookup table defined in assembly that you 
don’t want to put in RAM. In this case, you must define a pointer to the object 
and access it indirectly from C. 


The first step is to define the object. It is helpful, but not necessary, to put 
itin its own initialized section. Declare a global label that points to the begin- 
ning of the object. 


The object can be linked anywhere into the memory space. To access it in 
C, you must declare an additional C variable to point to the object. Initialize 
the pointer with the assembly language label declared for the object; re- 
member to remove the underscore. 


Figure 4—4 shows an example for accessing a variable that is not defined 
in .bss. 


Figure 4—4. Accessing a Variable that is not Defined in .bss from C 


(a) Assembly Language Program 


-global sine ; Declare variable as external 
.sect “sine tab” ; Make a separate section 
_ sine: 7 Phe Cable. Starts: here 
sE£toat. 0x0 
sfloat “0.015987 
-float 0.022145 


(b) C Program 


extern float sine[]; This is the object 
float *sine _p = sine; Declare a C pointer 
EO PON. Co aL 
sine p[4]; Access sinelikea 
normal array x / 
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4.5.2 


Note that a reference such as sine [4] will not work because the object is 
not in .bss and a direct reference such as this generates incorrect code. 


Inline Assembly Language 


Within a C program, you can use the asm statement to inject a single line 
of assembly language into the assembly language file that the compiler 
creates. A series of asm statements places sequential lines of assembly 
language into the compiler output with no intervening code. For more infor- 
mation about the asm statement, refer to Section 3.8 on page 3-11. 


ee ee a ee RT Ne ee ee ee 


Note: 


Inserting jumps or labels into C code may produce unpredictable results by 
confusing the register-tracking algorithms that the code generator uses. 
The asm statement is provided so that you can access features of the hard- 
ware which would be otherwise inaccessible from C. 


Do not change the value of a C variable; however, you can safely read the 
current value of any variable. 


In addition, do not use the asm statementto insert assembler directives that 
would change the assembly environment. 
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The asm statementis also useful for inserting comments in the compiler out- 
put; simply start the assembly code string with an asterisk (*) as shown be- 
low: 


asm(“**** this is an assembly language comment”); 


4.5.3 Modifying Compiler Output 
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You can inspect and change the assembly language output that the compiler 
produces by compiling the source and then editing the output file before 
assembling it. The note in Section 4.5.2 about disrupting the C environment 
also apply to modification of compiler output. 
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4.6 Interrupt Handling 


As long as you follow the guidelines in this section, C code can be inter- 
rupted and returned to without disrupting the C environment. When the C 
environment is initialized, the startup routine does not enable or disable 
interrupts. (Ifthe system is initialized via a hardware reset, interrupts are dis- 
abled). If your system uses interrupts, it is your responsibility to handle any 
required enabling or masking of interrupts. Such operations have no affect 
onthe C environment and can be easily incorporated with asm statements. 


4.6.1 Saving Registers During Interrupts 


When C code is interrupted, the interrupt routine must preserve the contents 
of all machine registers. A problem arises with the extended-precision reg- 
isters used for expression analysis (RO—R3): these registers can contain 
either integer or floating-point values, and an interrupt routine cannot deter- 
mine the type of value in a register. Thus, an interrupt routine must preserve 
all 40 bits of any of these registers that it modifies. This involves saving both 
the integer part (lower 32 bits) and the floating-point part (upper 32 bits). You 
can avoid this problem by not using these registers for handling interrupts. 


The following code saves and restores all 40 bits of a register: 


PUSH RO ; Save bottom 32 bits 
PUSHY RO ; Save top 32 bits 

POPF RO ; Restore top 32 bits 
POP RO ; Restore bottom 32 bits 


If the interrupt routine modifies R6 or R7, which are reserved for the float- 
ing-point register variables, only the floating-point contents must be 
preserved. These registers can contain only floating-point values. 


Any other registers that are modified by the interrupt routine can contain in- 
tegers (or pointers) only, so only the integer part (lower 32 bits) must be 
preserved. 


4.6.2 Using C Interrupt Routines 


Interrupts can be handled directly with C functions by using aspecial naming 
convention. C interrupt functions have names with the following format: 
c intnn 


nn is a two-digit interrupt number between 00 and 99 (for example, a valid 
interrupt routine name is c_int01). By following this convention for naming 
interrupt routines, you assure that the compiler uses the special register 
preservation requirements that are discussed in Section 4.6.1. 


4-23 


Interrupt Handi 
SHsemresesasesgseasseseseseeea he canenacataeeseeseacerseatenetesesessesesessasszecassezssrsaeatanacerseanotonosatstetsevasseteessosototosesnsesssoietesstatstetcesesssstestet 


RESP EU SESE LSEN NN ieesieaaee oats eetoaatneoneboseeesenaaaseaaaastobetanone eee svesseanbanozesesseeeserasaasanenageesesseanssneasebonenessasanesosesessesasstasssogeotevsssosososoponeseboansesssososoinetoneesssesssesssososobaconemsanetssssssasssoseansoestenesnacssesssoseseeasseaceeessaneeransosegneetay 


The name c_int00 is reserved for the system reset interrupt. This special 
interrupt routine initializes the system and calls the function main; c_int00 
does not save any registers because it has no caller. 


Ifa C interrupt routine does not call any other functions, only those registers 
that are actually used in the interrupt handler are saved and restored. How- 
ever, if a C interrupt routine does call other functions, these functions may 
modify unknown registers that are not used in the interrupt handler itself. For 
this reason, the routine saves all the expression registers if any other func- 
tions are called. This uses many extra instructions; if you are sure that a 
particular register will not be modified, you can hand-modify the compiled 
code so that an unused register is not saved and restored. 


A C interrupt routine is like any other C function in that it can have local vari- 
ables and register variables; however, it should be declared with no 
arguments. Interrupt handling functions should not be called directly. 


4.6.3 Assembly Language Interrupt Routines 
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Interrupts can also be handled with assembly language code, as long as the 
register conventions are followed. Like all assembly functions, interrupt rou- 
tines can use the stack, access global C variables, and call C functions 
normally. When calling C functions, be sure that all nondedicated registers 
are preserved because the C function can modify any of them. Of course, 
dedicated registers need not be saved because they are preserved by the 
C function. 
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4.7 Expression Analysis 


All C expressions are calculated using the registers designated for expres- 
sion analysis: 


Li Registers RO—R3 are used for expression evaluation. 
La Registers ARO—AR2 are used for indirection with pointers. 


Expressions are evaluated according to standard C precedence rules. 
When a binary operator is analyzed, the order of analysis of the operands 
is based on their relative complexity. The compiler tries to evaluate subex- 
pressions in a way that prevents saving temporary results, which are 
calculated in registers, off to memory. This does not apply to those operators 
that specify a particular order of evaluation (such as the comma, &«, and ||), 
which are always evaluated in the correct order. 


The compiler attempts to avoid using the address registers in evaluation 
because pipeline delays can result from using auxiliary registers for both 
computation and indirection. This is apparent in the code generated for 
pointer arithmetic, where the arithmetic is evaluated in RO—R3, then moved 
to an auxiliary register when the resulting pointer is actually used. 


Floating-point expressions are evaluated using the on-chip floating-point 
hardware. In general, this means that all floating-point operations are car- 
ried out with full extended precision (40 bits). However, in some cases an 
extended-precision temporary result in a register must be saved off to 
memory, in which case only 32 bits of precision are preserved. 
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4.8 Runtime-Support Math Routines 
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The TMS320C30 MPYI (multiply integer) instruction does not perform full 
32-bit multiplication; it uses only the lower 24 bits of each operand. Standard 
C requires full 32-bit multiplication. Therefore, a runtime-support function 
called MPY_I is provided to implement 32-bit integer multiplication. This 
function does not follow the standard C calling sequence; instead, operands 
are passed in registers RO and R1. The 32-bit product is returned in RO. The 
compiler uses the TMS320C30 MPYI instruction only in cases where ad- 
dress arithmetic is performed (such as during array indexing); because no 
address can have more than 24 bits, a 24x24 multiply is sufficient. You can 
use the —mm option to force the compiler to use MPY1 instructions for all inte- 
ger multiplies. 


Because the TMS320C30 has no division instructions, integer and 
floating-point division are performed via calls to additional runtime-support 
functions called DIV_| and DIV_F. Another function called MOD_| performs 
the integer modulo operation. Corresponding functions called DIV_U and 
MOD_U are used for unsigned integer division and modulo. Like MPY_I, 
these functions take their arguments from RO and R1 and return the result 
in RO. 


The runtime-support math functions can use volatile registers RO—R3 and 
the index registers IRO and !IR1 without saving them. Any other registers that 
are used must be saved. The versions of the functions supplied with the 
compiler use no additional registers. 


The runtime-support math functions are. written in assembly language. 
Object code for them is provided in the object library rts .1ib. Any of these 
functions that your program needs are linked in automatically if you name 
rts.lib as input at link time. 


The source code for these functions is in the source library rts.src. The 
source code has comments that describe the operation and timing of the 
functions. You can extract, inspect, and modify any of the math functions; 
be sure you follow the special calling conventions and register saving rules 
Outlined in this section. 
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Figure 4—5 summarizes the runtime-support math functions and names the 
files that contain the functions. 


Figure 4-5. Summary of Runtime-Support Math Functions 


Function 


DIV_F 
DIV_| 
DIV_U 
MOD_| 
MOD_U 
MPY_| 


Description 


Floating-point divide 
Integer divide 

Unsigned integer divide 
Integer modulo 
Unsigned integer modulo 


32x32 Integer multiply 


Source File 
il ae 
a ha a 
divu. 
modi. 
modu. 


mpyi. 


asm 


asm 


asm 


asm 


asm 


asm 
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4.9 Optimization 
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The TMS320C30 C compiler was designed with two major goals in mind: 


Ch 


Cd 


For general purpose C code, the TMS320C30 C compiler produces 
compiled code that performs nearly as well as hand-coded assembly 
language. 


Forcritical DSP algorithms, the TMS320C30 C compiler provides a sim- 
ple and accessible programming environment so that applications de- 
manding high performance can be implemented in assembly language. 


The compiler performs a wide variety of optimizations to improve the 
efficiency of compiled code. The degree of optimization relative to hand- 
coded assembly language for a given program is extremely dependent on 
how the program is written; if the code is written specifically with the C30 
compiler in mind, the generated code can be nearly as efficient as assembly 
language. 


The following list describes some of the optimizations and highlights 
particular strengths of the compiler: 


i 


Register Variables 


By using register variables, the compiler generates excellent code for 
expressions involving these variables. Register variables are particu- 
larly valuable as pointers. 


Register Tracking 


The compiler tracks the contents of registers so it avoids reloading val- 
ues if they are used again soon. Variables, constants, and structure ref- | 
erences (a.b) are tracked through straight-line code and forward 
branches. 


3-Operand Instructions 


By using 3-operand instructions whenever possible, the compiler 
preserves the contents of the registers and allows more flexibility in ad- 
dressing. These instructions are particularly effective in conjunction 
with register variables. 


Algebraic Reordering 


The compiler reorders expressions into algebraic equivalents to allow 
optimal evaluation. For example: —(a + b), which takes 3 instructions to 
evaluate, is written as —a —b, which only takes 2 instructions. 
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Optimization 


La Jump Optimizations 


The compiler unwinds jumps to jumps and eliminates dead code 
(unlabeled code following an unconditional jump). 


Li Loop Rotation 


The compiler evaluates loop conditionals at the top and bottom of 
loops, saving a costly extra jump into or out of a loop. In cases of simple 
counting loops (for (i= 0;i< 10;...))the initial entry conditional check is 
optimized out. | 


Lu Delayed Branches 


Where possible, the compiler uses delayed branches for unconditional 
branches, avoiding pipeline delays caused by standard branches. 


Cs Parallel Instructions 


Because of the restrictive addressing requirements of the parallel in- 
structions, it is difficult for the compiler to take advantage of them. How- 
ever, in cases where two adjacent instructions fit the addressing re- 
quirements, they are combined in parallel instructions. Also, the 
compiler uses parallel instructions for structure move operations. 


C4 Autoincrement Addressing 


For pointer expressions of the form *p++, “p—-, *++p, or “-—p, the com- 
piler uses efficient autoincrement addressing modes. 
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Note: 


If you use the —g option to generate symbolic debugging information, many 
of these optimizations are disabled because they disrupt the debugger. If 
you want to use symbolic debugging and still generate fully optimized code, 
use the —mn option on CL30; —mn re-enables the optimizations disabled 
by -g. 
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4.10 System Initialization 


Before you can run a C program, the C runtime environment must be 
created. This task is performed by the C boot routine, which is a function 
called c_int00. The runtime-support source library contains the source to 
this routine in a module named boot .asm. 


The c_int00 function can be called by reset hardware to begin running the 
system. The function is in the runtime support library (rts.1ib) and must 
be combined with the C object modules at link time. This occurs by default 
when you use the —c or -cr option in the linker and include rts.1ib as one 
of the linker input files. When C programs are linked, the linker sets the entry 
point value in the executable output module to the symbol c_intoo. 


The c_int00 function performs the following tasks in order to initialize the C 
environment: 


1) Defines a section called .stack for the system stack and sets up the ini- 
tial stack and frame pointers. 


2) Autoinitializes global variables by copying the data from the initialization 
tables in .cinit to the storage allocated for the variables in .bss. In the 
small model, the constant tables are also copied from .cinit to .bss. 


In the RAM initialization model, a loader performs this step before the 
program runs (it is not performed by the boot routine). 


3) Small memory model only—sets up the page pointer DP to point to the 
global storage page in .bss. 


4) Calls the function main to begin running the C program. 


You can replace or modify the boot routine to meet your system require- 
ments. However, the boot routine must perform the four operations listed 
above in order to correctly initialize the C environment. 


4.10.1 Autoinitialization of Variables and Constants 
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Some global variables must have initial values assigned to them before a 
C program starts running. The process of retrieving these variables’ data 
and initializing the variables with the data is called autoinitialization. 


The compiler builds tables in a special section called .cinit that contains 
data for initializing global and static variables. Each compiled module con- 
tains these initialization tables. The linker combines them into a single table 
(a single .cinit section). The boot routine uses this table to initialize all the 
variables that need values before the program starts running. 
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Instandard C, global and static variables that are not explicitly initialized are 
set to 0 before program execution. The TMS320C30 C compiler does not 
adhere to this convention. Any variable which must have an initial value of 
O must be explicitly initialized. 
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In the small memory model, any tables of long constant values or constant 
addresses must also be copied into the global data page at this time. Data 
for these tables is incorporated into the initialization tables in .cinit and thus 
is automatically copied at initialization time. 


There are two methods for copying the autoinitialization data into memory; 
these methods are called the RAM and ROM models of autoinitialization. 
Section 4.10.1.1 describes the format of the initialization tables, Section 
4.10.1.2 describes the RAM model of initialization, and Section 4.10.1.3 de- 
scribes the ROM model of initialization. 


4.10.1.1 Initialization Tables 


The tables in .cinit consist of variable size initialization records. Figure 4—6 
shows the format of the .cinit section and the initialization records. 


Figure 4—6. Format of Initialization Records in the .cinit Section 
.cinit Section 


initialization record 1 


IE initialization Record 


initialization record n 


La The first field of an initialization record is the size (in words) of the initial- 
ization data. 


La The second field is the starting address of the area within the .bss sec- 
tion, where the initialization data must be copied. (This field points to a 
variable’s space in .bss.) 


L! 


These first two fields are followed by one or more words of data. During 
autoinitialization, this data is copied to the specified address in .bss. 
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Each variable that must be autoinitialized has an initialization record 
in the .cinit section. 


For example, suppose two initialized variables are defined in C as follows: 


int i = 23; 
nt a Lod: 2S -f. Ly 2 Se 4S. Te 


The initialization information for these variables is: 


-sect esci nik ; Initialization section 
* Record for variable i 
-word 1 ; Length of data (1 word) 
word oe ; Address in .bss 
-word 23 ; Data 
* Record for variable a 
.word 5 ; Length of data (5 words) 
-word Ja ; Address in .bss 
-word Le 2povagD ; Data 


The .cinit must contain only initialization tables in this form. If you interface 
assembly language modules to your C program, do notuse the .cinit section 
for any other purpose. 


When you use the —c or -cr linker option, the linker links together the .cinit 
sections from all the C modules and appends a null word to the end of the 
composite .cinit section. This terminating record appears as a record with 
a size field of 0, marking the end of the initialization tables. 


4.10.1.2 RAM Initialization Model 
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The RAM model, specified with the —cr linker option, allows variables to be 
initialized at load time instead of at run time. This enhances system perform- 
ance by reducing boot time and by saving the memory that would ordinarily 
be used by the initialization tables. 


When you use the —cr linker option, the linker sets the STYP_COPY bit in 
the .cinit section’s header; this tells the loader not to load the .cinit section 
into memory. (The .cinit section occupies no space in the memory map.) 
The linker also sets the cinit section to —1 (normally, cinit would point 
to the beginning of the initialization tables). This indicates to the boot routine 
that the initialization tables are not present in memory; accordingly, no run- 
time initialization is performed at boot time. 


Note that you must use a smart loader to take advantage of the RAM model. 
When the program is loaded, the loader must be able to: 


La Detect the presence of the .cinit section in the object file. 


Ca Find out that STYP_COPY is set in the .cinit section header, so that it 
Knows not to copy the .cinit section into memory. 


Ca Understand the format of the initialization tables. 
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The loader then uses the initialization tables directly from the object file to 
initialize variables in .bss. 


Figure 4—7 illustrates the RAM model of autoinitialization. 


Figure 4—7. RAM Model of Autoinitialization 
Object File Memory 


.cinit 
section 


4.10.1.3 ROM Initialization Model 


The ROM model is the default method of the autoinitialization; to use this 
model, invoke the linker with the —c option. 


In this method, global variables are initialized at run time. The .cinit section 
is loaded into memory (possibly ROM) along with all the other sections. The 
linker defines a special symbol called cinit that points to the beginning of 
the initialization tables in memory. When the program begins running, the 
C boot routine copies data from the tables (pointed to by cinit) into the spe- 
cified variables in .bss. This allows initialization data to be stored in ROM 
and then copied to RAM each time the program is started. 
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Figure 4—8 illustrates the ROM model of autoinitialization. 


Figure 4—8. ROM Model of Autoinitialization 
Object File 


boot 
routine 
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Chapter 5 


Runtime-Support Functions 


some of the tasks that a C program must perform (such as floating-point 
arithmetic, string operations, and dynamic memory allocation) are not part 
of the C language. The runtime-support functions, which are included with 
the C compiler, are standard functions that perform these tasks. The 
runtime-support library rts.1ib contains the object code for each of the 
functions described in this chapter; the library rts. src contains the source 
to these functions as well as to other functions and routines. If you use any 
of the runtime-support functions, be sure to include rts. 1ib as linker input 
when you link your C program. 


This chapter is divided into three parts: 
Lk Part 1 describes header files and discusses their functions. 


C4 Part 2 summarizes the runtime-support functions according to 
category. 


Ci Part3 is an alphabetical reference. 


Topics in this chapter include: 


Section Page 
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5.2 Summary of Runtime-Support Functions and Macros ........ 5-9 
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5.1 Header Files 


Each runtime-support function is declared in a header file. Each header file 
declares: 


La A set of related functions (or macros), 
Ca Any types that you need to use the functions, and 
La Any macros that you need to use the functions. 


There are header files that declare the runtime-support functions: 


assert.h limits.h stddef.h 
ctype.h math.h stdlib.h 
errno.h stdarg.h string.h 
float.h time.h 


In order to use a runtime-support function, you must first use the #include 
preprocessor directive to include the header file that declares the function. 
For example, the isdigit function is declared by the ct ype.h header. Before 
you can use the isdigit function, you must first include the ctype.h file: 


#include <ctype.h> 


val = isdigit (num); 


You can include headers in any order. You must include a header before you 
reference any of the functions or objects that it declares. 


Sections 5.1.1 through 5.1.10 describe the header files that are included 
with the TMS320C30 C compiler. Section 5.2, page 5-9, lists the functions 
that these headers declare. 


5.1.1. Diagnostic Messages (assert .h) 
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The assert .h header defines the assert macro, which inserts diagnostic 
failure messages into programs at runtime. The assert macro tests a 
runtime expression. If the expression is true, the program continues 
running. If the expression is false, the macro outputs a message that 
contains the expression, the source file name, and the line number of the 
statement that contains the expression; then, the program terminates (via 
the abort function). 


The assert .h header refers to another macro named NDEBUG (assert .h 
does not define NDEBUG). If you have defined NDEBUG as a macro name 
when you include assert .h, then the assert macro is turned off and does 
nothing. If NDEBUG /s not defined, then the assert macro is enabled. 
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The assert macro is defined as follows: 


#ifdef NDEBUG 

#define assert (ignore) 

#else 

#define assert(expr) \ 

if (!(expr)) {printf (”Assertion failed, (expr), file s,\ 
line d\n”, (FILE _, _ _LINE_ _); abort(); } 

#endif 


5.1.2 Character Typing and Conversion (ctype .h) 


The ctype.h header declares functions that test (type) and convert 
characters. 


For example, a character-typing function may test a character to determine 
whether it is a letter, a printing character, a hexadecimal digit, etc. These 
functions return a value of true (a nonzero value) or false (0). 


The character-conversion functions convert characters to lower case, upper 
case, or ASCII and return the converted character. 


Character-typing functions have names in the form isxxx (for example, 
isdigit). Character-conversion functions have names in the form toxxx (for 
example, toupper). 


The ctype.h header also contains macro definitions that perform these 
same operations; the macros run faster than the corresponding functions. 
The typing macros expand to a lookup operation in an array of flags (this 
array is defined in ctype.c). The macros have the same name as the 
corresponding functions, but each macro is prefixed with an underscore (for 
example, _/sdigit). 


5.1.3 Limits (float.h and limits.h) 


The float.h and limits.h headers define macros that expand to useful 
limits and parameters of the TMS320C30’s numeric representations. 
Table 5—1 and Table 5-2 list these macros and the limits they are 
associated with. 
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Table 5-1. Macros that Supply Integer Type Range Limits (limits .h) 
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Macro 
CHAR_BIT 
SCHAR_MIN 
SCHAR_MAX 
UCHAR_MAX 
CHAR_MIN 
CHAR_MAX 
SHRT_MIN 
SHRT_MAX 
USHRT_MAX 
INT_MIN 
INT_MAX 
UINT_MAX 
LONG_MIN 
LONG_MAX 
ULONG_MAX 


Value 


32 
—2147483648 
2147483647 
4294967295 
SCHAR_MIN 
SCHAR_MAX 
—2147483648 
2147483647 
4294967295 
—2147483648 
2147483647 
4294967295 
—2147483648 
2147483647 
4294967295 


Description 
Number of bits in type char 
Minimum value for a signed char 
Maximum value for a signed char 
Maximum value for an unsigned char 
Minimum value for a char 
Maximum value for a char 
Minimum value for a short int 
Maximum value for a short int 
Maximum value for an unsigned short int 
Minimum value for an int 
Maximum value for an int 
Maximum value for an unsigned int 
Minimum value for a long int 
Maximum value for a long int 


Maximum value for an unsigned long int 
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Table 5—2. Macros that Supply Floating-Point Range Limits (£10at .h) 


FLT RADIX Base or radix of exponent representation 

FLT ROUNDS 1 Rounding mode for floating-point addition 
(rounds to nearest integer) 

FLT DIG Number of decimal digits of precision for a float, 

DBL_DIG double, or long double 

LDBL_DIG 

FLT_MANT_DIG 24 Number of base-FLT_RADIX digits in the 

DBL_MANT DIG mantissa of a float, double, or long double 

LDBL_MANT_DIG 

FLT MIN _EXP ~126 Minimum negative integer such that FLT_RADIX 

DBL _MIN_EXP raised to that power minus 1 is a normalized 

LDBL_MIN_EXP float, double, or long double 

FLT MAX_EXP 128 Maximum negative integer such that FLT_RADIX 

DBL_MAX_EXP raised to that power minus 1 is a representive 

LDBL_MAX_EXP finite float, double, or long double 

FLT_EPSILON 1.1920929E-—07 Minimum positive float, double, or long double 

DBL_EPSILON number x such that 1.0+ x#1.0 

LDBL_EPSILON 

FLT MIN 5.877481 7E-39 Minimum positive float, double, or long double 

DBL_MIN 

LDBL_MIN 

FLT MAX 3.4028235E+38 Maximum positive float, double, or long double 

DBL_MAX 

LDBL_MAX 

FLT _MIN_10 EXP ~—39 Minimum negative integers such that 10 raised to 

DBL_MIN_ 10 EXP that power is in the range of normalized floats, 

LDBL_MIN_10_EXP doubles, or long doubles 

FLT MAX_10_ EXP 38 Maximum positive integers such that 10 raised to 


DBL_MAX_10_EXP 


that power is in the range of finite floats, doubles, 
LDBL_MAX_10_EXP 


or long doubles 


Key to prefixes: 


FLT _ applies to type float 
DBL_ _ applies to type double 
LDBL_ applies to type long double 


5.1.4 Floating-Point Math (math .h) 


The math.h header defines several trigonometric, exponential, and 
hyperbolic math functions. These math functions expect double-precision 
floating-point arguments and return double-precision floating-point values. 


The math.h header also defines one macro named HUGE_VAL; the math 
functions use this macro to represent out-or-range values. When a function 
produces a floating-point return value that is too large to be represented, it 
returns HUGE_VAL instead. 
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5.1.5 Error Reporting (errno .h) 


Errors can occur in a math function if the invalid parameter values are 
passed to the function or if the function returns a result that is outside the 
defined range for the type of the result. When this happens, a variable 
named errno is set to the value of one of the following macros: 


[4 EDOM, for domain errors (invalid parameter), or 
[a ERANGE, for range errors (invalid result). 


C code that calls a math function can read the value of errno to check for 
error conditions. The errno variable is declared in errno.h and defined in 
errno.c. 


5.1.6 Variable Arguments (stdarg.h) 


Some functions can have a variable number of arguments whose types can 
differ; such a function is called a variable-argument function. The stdarg.h 
header declares three macros and a type that help you to use variable- 
argument functions: 


La Thethree macros are va_start, va_arg, and va_end. These macros are 
used when the number and type of arguments may vary each time a 
function is called. 


La The type, va_list, is a pointer type that can hold information for va_start, 
va_end, and va_arg. 


A variable-argument function can use the objects declared by stdarg.h to 
step through its argument list at run time, when it knows the number and 
types of arguments actually passed to it. 


5.1.7 Standard Definitions (stddef .h) 


The stddef.hheader defines two types andtwo macros. The types include: 


La ptrdiff_t, a signed integer type that is the data type resulting from the 
subtraction of two pointers; and 


La size_t, an unsigned integer type that is the data type of the sizeof 
operator. 


The macros include: 
La The NULL macro, which expands to a null pointer constant(0), and 


La The offsetof(type, identifier) macro, which expands to an integer that 
has type size_t. The result is the value of an offset in bytes to a structure 
member (identifier) from the beginning of its structure (type). 


These types and macros are used by several of the runtime-support 
functions. 


Runtime-Support Functions 


Header Files 


5.1.8 General Utilities (stdlib .h) 


The stdlib.h header declares several functions, one macro, and two 
types. The macro is named RAND_MAxX. The types include: 


Li div_t, a structure type that is the type of the value returned by the div 
function, and 


C4 /div_t, a structure type that is the type of the value returned by the Idiv 
function. 


The stdlib.h header also declares many of the common library functions: 


Li Memory management functions that allow you to allocate and 
deallocate packets of memory. The amount of memory that these 
functions can use is defined by the constant  _sySmem s1zz in the 
runtime-support module sysmem.asm. (This module is archived in the 
file rts.src.) By default, the amount of memory available for allocation 
is 2048 words. You can change this amount by modifying 
_ _SYSMEM_ SIZE and reassembling sysmem.asm. 


La String conversion functions that convert strings to numeric 
representations. 


La Searching and sorting functions that allow you to search and sort 
arrays. 


La Sequence-generation functions that allow you to generate a pseudo- 
random sequence and allow you to choose a starting point for a 
sequence. 


La Program-exit functions that allow your program to terminate normally 
or abnormally. | 


La Integer-arithmetic that is not provided as a standard part of the C 
language. 


5.1.9 String Functions (string.h) 


The string.hheader declares standard functions that allow you to perform 
the following tasks with character arrays (strings): 


La Move or copy entire strings or portions of strings, 
(4 Concatenate strings, 

C4 Compare strings, 

La Search strings for characters or other strings, and 
La Find the length of a string. 


In C, all character strings are terminated with a 0 (null) character. The string 
functions named strxxx all operate according to this convention. Additional 
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functions that are also declared in string.h allow you to perform 
corresponding operations on arbitrary sequences of bytes (data objects), 
where a0 value does not terminate the object. These functions have names 
such as memxxx. 


When you use functions that move or copy strings, be sure that the 
destination is large enough to contain the result. 
5.1.10 Time Functions (time .h) 


The time.h header declares one macro, several types, and functions that 
manipulate dates and time. The functions deal with several types of time: 


Li Calendar time represents the current date (according to the Gregorian 
calendar) and time. 


Lu Local time is the calendar time expressed for a specific time zone. 
Li Daylight savings time is a variation of local time. 


The time.h header declares one macro, CLK_TCK, which is the number 
per second of the value returned by the clock function. 


The header declares three types: 
Lk clock_t, an arithmetic type that represents time; 
La time_t, an arithmetic type that represents time, and 


La tmis a structure that holds the components of calendar time, called 
broken-down time. The structure has the following members: 


int: tim-s¢ec; /* seconds after the minute (0-59) a 
Le tm min; /* minutes after the hour (0-59) * / 
THit tm hour; /* hours after midnight (0-23) * / 
int tm _mday; /* day of the month (1-31) * / 
int tm_mon; /* months since January (0-11) * / 
int tm year; /* years since 1900 (0-99) ows 
int tm_wday; /* days since Saturday (0-6) * / 
int tm yday; /* days since January 1 (0-365) * 
int tm_isdst; /* Daylight Savings Time ee * / 


tm_isdst Can have one of three values: 

H A positive value if Daylight Savings Time is in effect. 
m Zero if Daylight Savings Time is not in effect. 

B A negative value if the information is not available. 


Note: 


All of the time functions depend on the clock() and time() functions, which 
you must customize for your system. 
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5.2 Summary of Runtime-Support Functions and Macros 
Refer to the following pages for information about functions and macros: 


Function or Macro Page 
Error Message MaCl0 sii ss. cow cia ale Pew Ta W eardied ekookas 5-10 
Character Typing Conversion Functions ..................005 5-10 
Floating-Point Math Functions ......... 0.0.0.0 cece eee ees 5-11 
Variable Argument Functions and Macros .................-.. 5-12 
General Vuities : ¢:4-0is coi abaedcncdawa eid abt ei ted weenie 5-12 
DINING: FUNCHONS :< nidc 3-3 A eed, boa lees wae M Ae Se ee Led 5-14 
WING FUNCHONS 2-8-5 dando -hatee do haiaeia bah ewer on Be ek 5-15 
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Error Message Macro 
(Header File: assert .h) 


Macro and Syntax Description 


void assert (expression) 
int expression; 


Inserts diagnostic messages into programs 


Character Typing Conversion Functions 
(Header File: ct ype .h) 


Function and Syntax Description 
int isalnum (c) Tests c to see if it’s an alphanumeric-ASCIl 
Shar oc: character 
int isalpha (c) Tests c to see if it’s an alphabetic-ASCIl character 
char c: 
int aisascii (c) Tests c to see if it's an ASCII character 
char c: 
int isentrl (c) Tests c to see if it's a control character 
char c: 
int isdigit(c) Tests c to see if it's a numeric character 
char c: 
int isgraph (c) Tests c to see if it’s any printing character except a 
char c: space 


int islower (c) 
char c: 


int isprint (c) 
char c: 


int ispunct (c) 
char c: 


int isspace (c) 
char -¢: 
int isupper (c) 


char c: 


int isxdigit (c) 
char -¢: 


char toascii (c) 
char c: 


char tolower (c) 
char c: 


char toupper (c) 
char c: 
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Tests c to see if it’s a lowercase alphabetic ASCII 
character 


Tests c to see if it’s a printable ASCIi character 
(including spaces) 


Tests c to see if it's an ASCII punctuation character 


Tests c to see if it's an ASCII spacebar, tab 
(horizontal or vertical), carriage return, formfeed, or 
newline characters 


Tests c to see if it's an uppercase ASCII alphabetic 
character 

Tests c to see if it’s a hexadecimal digit 

Masks c into a legal ASCII value 


Converts c_ to lowercase if it's uppercase 


Converts c to uppercase if it’s lowercase 
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Summary of Runtime-Support Functions and Macros 


eee 


Floating-Point Math Functions 
(Header File: math.h) 


Function and Syntax Description 


double acos (x) 
double x; 


double asin (x) 
double: x; 


double atan (x) 
double x; 


double atan2 (y,X) 
double y,X; 


double ceil (x) 
double x; 


double cos (x) 
double x; 


double cosh (x) 
double x; 


double exp (x) 
double <x; 


double fabs (x) 
double x; 


double floor (x) 
double x; 


double fmod (x, y) 
double x, y; 


double frexp (value, exp) 
double value; 
int *exXDP; 


double ldexp (x, exp) 
double x; 
int exp; 


double log (x) 
double x; 


double logl10 (x) 
double x; 


doublemod£f (value, iptr) 
double value; 
int Ei © aan ay 


double pow (x, y) 
double x, y; 


double Sin (x) 
double x; 


double Sinh (x) 
double x; 


Returns the arc cosine of x 

Returns the arc sine of x 

Returns the arc tangent of x 

Returns the inverse tangent of y/x 

= the smallest integer greater than or equal 
x 

Returns the cosine of x 

Returns the hyperbolic cosine of x 

Returns the exponential function of x 

Returns the absolute value of x 

Returns the largest integer less than or equal to x 


Returns the floating-point remainder of x/y 


Breaks value into a normalized fraction and an 
integer power of 2 


Multiplies x by an integer power of 2 


Returns the natural logarithm of x 
Returns the base-10 logarithm of x 


Breaks value into into a signed integer and a 
signed fraction 


Returns x raised to the power y 
Returns the sine of x 


Returns the hyperbolic sine of x 
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Floating-Point Math Functions 


(continued) 
Function and Syntax Description 
double sqrt (x) Returns the nonnegative square root of x 
double x; 
double tan (x) Returns the tangent of x 
double x; 
double tanh (x) Returns the hyperbolic tangent of x 


double x; 


Variable Argument Functions and Macros 
(Header File: stdarg-h) 


Function/Macro and Syntax Description 
type va_arg (ap, type) Accesses the next argument of type type ina 
va_list ap; variable-argument list 
void va_end (ap) Resets the calling mechanism after using va_arg 
va_list ap; 
void va_start (ap, parmN) Initializes ap to point to the first operand in the 
va_list ap; variable-argument list 


General Utilities 
(Header File: stdlib.h) 


Function and Syntax Description 
int abs (3) Returns the absolute value of 5 
ant. VF 
void abort () Terminates a program abnormally 
void atexit (fun) Registers the function pointed to by fun, to be 
void (*fun) (); called with out arguments at normal program 
termination 
double atof (nptr) Converts a string to a floating-point value 


char *nptr; 


int atoi (nptr) Converts astring to an integer value 
char *nptr; 


long int atol (nptr) Converts astring to a long integer 
char *nptr; 


void *bsearch (key, base, nmemb, size, compar) 


void *key, *base; Searches through an array of nmemb objects for 
size t nmemb, size; the object that key points to 
int (*compar) (); 

void *calloc (nmemb, size) Allocates and clears memory for nmemb objects, 
size_t nmemb, size each of size bytes 
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Summary of Runtime-Support Functions and Macros 


General Utilities 
(continued) 


Function and Syntax 


div_t div (numer, denom) 
int numer, denom 


void exit (status) 
int status; 


void 
void 


free (ptr) 
SOC DY 


long int labs (3) 
LONG sae: 4G 


ldiv_tildiv (numer, denom) 
long int numer, denom 


int ltoa (n, buffer) 
long n; 
char *buffer; 


void *malloc (size) 
size t size 


void minit () 
char *movmem (src,dest, count) 
char *src, *dest; 


Ine count; 


void qsort (base, nmemb, size, compar) 


void *base; 
size t nmemb, size; 
int (*compar) (); 


int rand () 


void*realloc (ptr, size) 
void “per; 
size t size; 


void srand (seed) 
unsigned int seed; 


double 
char 


strtod (nptr, endptr) 
*nptr, **endptr; 


long int strtol (nptr, endptr, base) 
Char -*nptr, **endpten; 
int base; 


unsigned longint strtoul 
Char *nptr, **endptr; 
int base; ~~ 


Description 


Divides numer by denom 

Terminates a program normally 

Deallocates memory space allocated by malloc, 
calloc, or realloc 

Returns the absolute value of 5 


Divides numer by denom 


Converts n to the equivalent string 


Allocates memory for an object of size bytes 
Resets all the memory previously allocated by 


malloc, calloc, Of realloc 


Moves count bytes from src to dest 


Sorts an array of nmemb members; base points 
to the first member of the unsorted array, and 
size specifies the size of each member 


Returns a sequence of pseudo-random integers in 


the range 0 to RAND_ MAX 


Changes the size of an allocated memory space 


Resets the random number generator 
Converts a string to a floating-point value 


Converts a string to a long integer 


Converts a string to an unsigned long integer 
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String Functions 
(Header File: string.h) 


Function and Syntax Description 
void *memchr(s, c, Nn) Finds the first occurrence of c in the first n charac- 
void *s; ters of s 
int Cc; 


size t n; 


int memcemp (sl, s2, n) Compares the first n characters of s1 to s2 
void *S1Ly. *S27 
size_t n; 


void *memcpy (sl, s2, n) Copies n characters from s1 to s2 
void *sl, *s2; 
Size t n; 


void *memmove (sl, s2, n) Moves n characters from si to s2 
void KSi> *S25 
Size t n; 


void *memset (s, c, n) Copies the value of c into the first n characters of s 
void *s; 
int Cc; 


size t n; 


char *streat (sl, s2) Appends s1 to the end of s2 
char: *sl;: *52; 

char *strchr (s, c) Finds the first occurrence of character c ins 
char *s; 
in. Cy 

int stremp (sl, s2) Compares strings and returns one of the following 
char *sl, *s2; values: <Qif si is less than s2; =0 if s1 is equal 
is greater than s2 to s2; >Oif si is greater than s2 

int .*strceoll (sl, s2) Compares strings and returns one of the following 
char *sl, *s2; values, depending on the locale: <0 if s1 is less 

than s2; =Oif sl is equal to s2; >0 if s1 is greater 
than s2 

char *strepy (sl, s2) Copies string s2 into s1 
char *sl, *s2Z; 

size t strespn (sl, s2) Returns the length of the initial segment of s1 that 
char *sl, *sl; is made up entirely of characters that are not in s2 

char *strerror (errnum) Maps the error number in errnum to an error 
int errnum; message string 

size t strlen (s) Returns the length of a string 
char *s; 

char *strncat (sl, s2, n) Appends up to n characters from si to s2 
char *sl,.*S2} 


Size ct n; 
int *strnemp (sl, s2, n) Compares up to n characters in two strings 


char *sl, *s2; 
Size t n; 
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Summary of Runtime-Support Functions and Macros 


String Functions 


(continued) 
Function and Syntax Description 
char *strnepy (sl, s2, n) Copies up to n characters of a s2 to s1 
char “si, 452; 
size t n; 
char *strpbrk (sl, s2) Locates the first occurrence in s1 of any character 
char *sl, *s2; from s2 
char *strrchr (s ,c) Finds the last occurrence of character c in s 
char *s; 
ant. “CF 
size t  strspn (sl, s2) Returns the length of the initial segment of s1, 
char *sl, *s2; which is entirely made up of characters from s2 
char *strstr (sl, s2) Finds the first occurrence of a s2 to s1 
char *sl, *s2; 
char *strtok (sl, s2) Breaks s1 into a series of tokens, each delimited 
char *sl, *s2; by a character from s2 


Time Functions 
(Header File: time.h) 


Function and Syntax Description 
char *asctime (timeptr) Converts a time to a string 
struct tm *timeptr; 
clock t clock () Determines the processor time used 
char *otime (timeptr) Converts calendar time to local time 


struct tm *timeptr; 


double difftime (timel,time0) Returns the difference between two calendar times 
time t timel, tim0; 
struct tm *gmtime (timer) Converts calendar time to Greenwich Mean Time 
time t *timer; 
structtm *localtime (timer) Converts calendar time to local time 
time t *timer; 


time _t mktime (timeptr) Converts local time to calendar time 
struct tm *timeptr; 


size t strftime (s, maxsize, format, timeptr) 


char *s, *format; Formats a time into a character string 
size t maxsize; 
struct tm *timeptr; 


time_t time (timer) Returns the current calendar time 
time t *timer; 
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5.3 Functions Reference 


The remainder of this chapter is a reference. Generally, the functions are 
organized alphabetically, one function per page; however, related functions 
(such as isalpha and isascii) are presented together on one page. Here’s 
an alphabetical table of contents for the functions reference: 
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Defined in 


Description 
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#include <stdlib.h> 
void abort( ) 


exit.cinrts.sre 


The abort function usually terminates a program with an error code. The 
TMS320C30 implementation of the abort function calls the exit function with 
a value of 0, and is defined as follows: 


void abort () 


{ 
exit (0); 
} 


This makes the abort function functionally equivalent to the exit function. 


Runtime-Support Functions 


Absolute Value abs/ 


labs 


cegeseceres esnae ses eceesete! esagetenesaneaeseaeaeee 


Syntax #include <stdlib.h> 


int abs(j) 
SNE -<y7 


long int labs (k) 
long int k; 


Definedin abs.cinrts.sre 


Description The C compiler supports two functions that return the absolute value of an 
integer: 


La The abs function returns the absolute value of an integer, 5. 
La The labs function returns the absolute value of a long integer, k. 


Since intand long intare functionally equivalent types in TMS320C30 C, the 
abs and labs functions are also functionally equivalent. 
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a 

Syntax #include <math.h> 


double acos (x) 
double x; 


Definedin§ asin.objinrts.lib 


Description The acos function returns the arc cosine of a floating-point argument; x. x 


must be in the range [—1,1]. The return value is an angle in the range [0,7] 
radians. 


Example double realval, radians; 


return (rrealval = 1.0; 
radians = acos(realval) ; 


return (radians); /* acos return T/2 */ 
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Syntax 


Defined in 


Description 


SRAM RRR RRR ER Sees 


#include <time.h> 


char *asctime(timeptr) 
struct tm *timeptr; 


asctime.cinrts.sre 


The asctime function converts a broken-down time into a string with the 
following form: 


Mon Jan 11 11:18:36 1988 \n\O 
The function returns a pointer to the converted string. 


For more information about the functions and types that the time.h header 
declares, refer to Section 5.1.10 on page 5-8. 
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Syntax #include <math.h> 


double asin (x) 
double x; 


Definedin asin.objinxrts.lib 


Description The asin function returns the arc sine of a floating-point argument; x. x must 


be in the range [—1,1]. The return value is an angle in the range [—1/2,70/2] 
radians. 


Example double realval, radians; 


Le Oe 


radians = asin(realval); /* asin returns 7/2 */ 


realval 
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Syntax 


Defined in 


Description 


Example 


Insert Diagnostic Information Macro assert 


Se 


#include <assert.h> 


void assert (expression) 
int expression; 


assert.h aS Macros 


The assert macro tests an expression; depending on the value of the ex- 
pression, assert either aborts execution and issues a message or continues 
execution. This macro is useful for debugging. 


[a If expression is false, the assert macro writes information about the 
particular call that failed to the standard output, and then aborts 
execution. 


La If expression is true, the assert macro does nothing. 


The header file that declares the assert macro refers to another macro, 
NDEBUG. If you have defined NDEBUG as a macro name when the as- 
sert .h header is included inthe source file, then the assert macro is defined 
as: 


#define assert (ignore) 


If NDEBUG is not defined when assert .his included, thenthe assert macro 
is defined as: 


#define assert(expr) \ 
1f (!(expr)) { 
printf(”Assertion failed, (expr), file %s, 
line d\n”, FILE __—iLINE__) 
abort (); } 


In this example, an integer i is divided by another integer 5. Since dividing 
by 0 is an illegal operation, the example uses the assert macro to test 5 be- 
fore the division. If j= =0, assert issues a message and aborts the program. 
int 2 a 

assert (4); 

gq = i/j; 
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Syntax #include <math.h> 


double atan (x) 
double x; 


Definedin atan.objinxrts.lib 


Description The atan function returns the arc tangent of a floating-point argument, x. 
The return value is an angle in the range [—1/2,7t/2] radians. 


Example double realval, radians; 


G..0; 
radians = atan(realval); /* return value = 0 */ 


realval 
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Cartesian Arc Tangent atan2 
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Syntax #include <math.h> 
double atan2(y, x) 

double y, x; 

Definedin  atan.ob}j inrts.lib 


Description The atan2 function returns the inverse tangent of y/x. The function uses the 
signs of the arguments to determine the quadrant of the return value. Both 
arguments cannot be 0. The return value is an angle in the range [-7.,7(] 
radians. 


Example double rvalu, rvalv; 
double radians; 


OO 
rvalv = 1.0; 


rvalu 


radians = atan2(rvalr, rvalu); /* return value = 0 */ 
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Syntax #include <stdlib.h> 


void atexit (fun) 
void (*fun) (); 


Definedin exit.cinrts.sre 
Description The atexit function registers the function that is pointed to by fun, to be 


called without arguments at normal program termination. Up to 32 functions 
can be registered. 


When the program exits through a call to the exit function, the functions that 
were registered are called, without arguments, in reverse order of their 
registration. 
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Syntax 


Defined in 


Description 


Jesecetecete 


ftinclude <stdlib.h> 


double atof(nptr) 
char *nptxr; 

int atoi(nptr) 
char “*nptxr? 

long int atol (nptr) 
char *nptr; 


atof.cand atoi.cinrts.sre 
Three functions convert strings to numeric representations: 


La The atof function converts a string to a floating-point value. Argument 
nptr points to the string; the string must have the following format: 


[space] [sign] digits [.digits] [e/E [sign] integer] 


La The atoi function converts a string to an integer. Argument npt r points 
to the string; the string must have the following format: 


[space] [sign] digits 


La The atol function converts a string to a long integer. Argument nptr 
points to the string; the string must have the following format: 


[space] [sign] digits 


The space is indicated by a space (character), a horizontal or vertical tab, 
a carriage return, a form feed, or anewline. Following the space is an option- 
al sign, and then digits that represent the integer portion of the number. The 
fractional part of the number follows, then the exponent, including an option- 
al sign. 


The first character that cannot be part of the number terminates the string. 


since intand long are functionally equivalent in TMS320C30 C, the atoi and 
atol functions are also functionally equivalent. 


The functions do not handle any overflow resulting from the conversion. 
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Syntax 


Defined in 


Description 
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#include <stdlib.h> 

void *bsearch(key, base, nmemb, size, compar) 
void *key, *base; 
size t nmemb, size; 
int (*compar) (); 


bsearch.cinrts.sre 


The bsearch function searches through an array of nmemb objects for a 
member that matches the object that key points to. Argument base points 
to the first member in the array; size specifies the size (in bytes) of each 
member. 


The contents of the array must be in ascending, sorted order. If a match is 
found, the function returns a pointer to the matching member of the array; 
if no match is found, the function returns a null pointer (0). 


Argument compar points to a function that compares key to the array 
elements. The comparison function should be declared as: 


int cmp(ptrl; ptr2) 
void *ptrl, -*ptr2; 


The cmp function compares the objects that prt 1 and ptr2 point to and re- 
turns one of the following values: 


< 0 if *ptri1 isless than *ptr2. 
O if *ptr1 is equalto *ptr2. 
> 0 if *ptri is greater than *ptr2. 


Runtime-Support Functions 
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Syntax #include <stdlib.h> 


void *calloc(nmemb, size) 
Size t nmemb; /* number of items to allocate */ 
size t size; /* size (in bytes) of each item */ 


Definedin = memory.cinrts.sre 


Description The calloc function allocates size bytes for each of nmemb objects and re- 
turns a pointer to the space. The function initializes the allocated memory 
to all Os. If it cannot allocate the memory (that Is, if it runs out of memory), 
it returns a null pointer (0). 


The memory that calloc uses is ina special memory poolorheap. An assem- 
bly language module called sysmem. asmdefines this memory pool as unini- 
tialized named section called .sysmem. The constant | SYSMEM SIZE de- 
fines the size of the heap as 2048 words. If necessary, you can change the 
size of the heap by changing the valueof | SYSMEM SIZE and reassem- 
bling sysmem.asm. For more information, refer to Section 4.1.4, Dynamic 
Memory Allocation, on page 4-6. 


Example This example uses the calloc routine to allocate and clear 10 bytes. 
prt = calloc (10,2) ; /*Allocate and clear 20 bytes */ 
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ceil Ceiling 
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Syntax #include <math.h> 


double ceil (x) 
double x; 


Definedin§ floor.objinrts.lib 


Description The ceil function returns a floating-point number that represents the small- 
est integer greater than or equal to x. 


Example extern double ceil(); 


double answer; 


answer = ceil (3.1415); /* answer 4.0 */ 


=350) */ 


i 


answer = ceil(-3.5); /* answer 
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Syntax 


Defined in 


Description 


SOR SE RE aR eR ES 


#include <time.h> 
clock t clock() 


clock.cinrts.sre 


The clock function determines the amount of processor time used. It returns 
an approximation of the processor time used by a program since the pro- 
gram began running. The time in seconds is the return value divided by the 
value of the macro CLK_TCK. 


If the processor time is not available or cannot be represented, the clock 
function returns the value of (clock_t) —1. 


(ne ee ee ee 


Note: 


The clock function is target-system specific, so you must write your own 
clock function. You must also define the CLK_TCK macro according to the 
granularity of your clock, so that the value returned by clock () (number of 
clock ticks) can be divided by CLK_TCK to produce a value in seconds. 


ee ne a ae Te aT Ie Se EN RI SR oe en re 


For more information about the functions and types that the time.h header 
declares, refer to Section 5.1.10 on page 5-8. 
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Syntax 


Defined in 


Description 


Example 
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#include <math.h> 
double cos (x) 
double x; 


sin.objinrts.lib 


The cos function returns the cosine of a floating-point number, x. x is an 
angle expressed in radians. An argument with a large magnitude may 
produce a result with little or no significance. 


double radians, cval; /* cos returns cval */ 
radians = 3.1415927; 
cval = cos (radians) ; /* return value = -1.0 */ 


Runtime-Support Functions 


Hyperbolic Cosine cosh 


Syntax #include <math.h> 


double cosh (x) 
double x; 


Definedin  sinh.objinxrts.lib 


Description The cosh function returns the hyperbolic cosine of a floating-point number, 
x. A range error occurs if the magnitude of the argument is too large. 


Example double x, y; 


x =O ..07 
y = cosh (x) ; /* return value = 1.0 */ 
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Syntax #include <time.h> 


char *ctime (timer) 
time t *timer; 


Defined in ctime.cinrts.sre 
Description The ctime function converts a calendar time (pointed to by timer) to local 
time, in the form of a string. This is equivalent to: 


asctime (localtime (timer) ) 


The function returns the pointer returned by the asctime function with that 
broken-down time as an argument. 


For more information about the functions and types that the time. h header 
declares, refer to Section 5.1.10 on page 5-8. 
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Time Difference difftime 


Syntax #include <time.h> 


double difftime(timel, time0) 
time t timel, time0; 


Defined in gdifftime.cinrts.sre 


Description The difftime function calculates the difference between two calendar times, 
timel minus timeo. The return value expresses seconds. 


For more information about the functions and types that the time .h header 
declares, refer to Section 5.1.10 on page 5-8. 
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Syntax 


Defined in 


Description 
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#include <stdlib.h> 


div _t div(numer, denom) 
int numer, denom; 
idiv_t ldiv(numer, denom) 

long int numer, denom; 


div.cinrts.sre 


Two functions support integer division by returning numer divided by denom. 
You can use these functions to get both the quotient and the remainder in 
a single operation. 


[i The div function performs integer division. The input arguments are in- 
tegers; the function returns the quotient and the remainder in astructure 
of type div_t. The structure is defined as follows: 


typedef struct 


{ 
ant “quol; /* quotient */ 
int rem; /* remainder */ 
} daiv_t; 


La The Idiv function performs /ong integer division. The input arguments 
are long integers; the function returns the quotient and the remainder 
in a structure of type Idiv_t. The structure is defined as follows: 


typedef struct 


{ 
long int quot; /* ‘quotient. *7 
long int rem; /* remainder */ 
} bday. 0 


lf the division produces a remainder, then the sign of the quotient is the same 
as the algebraic quotient, and the magnitude of the resulting quotient is the 
largest integer less than the magnitude of the algebraic quotient. 


Since ints and longs are equivalent types in TMS320C30 C, these functions 
are also equivalent. 


Runtime-Support Functions 


Defined in 


Description 
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#include <stdlib.h> 


void exit (status) 
int status; 


exit.cinrts.sre 


The exit function terminates a program normally. All functions registered by 
the atexit function are called, in reverse order of their registration. 


You can modify the exit function to perform application-specific shutdown 
tasks. The unmodified function simply runs in an infinite loop until the sys- 
tem is reset. 


Note that the exit function cannot return to its caller. 
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Syntax #include <math.h> 


double exp (x) 
double x; 


Definedin = exp.objinrts.1lib 


Description The exp function returns the exponential function of real number x. The re- 
turn value is the number e raised to the power x. A range error occurs if the 
magnitude of x is too large. 


Example double x, y; 


x = 2.0; 
y = exp (x); /* y = 7.38, which is e**2.0 */ 
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Syntax #include <math.h> 


double fabs (x) 
double: x; 


Definedin fabs.objinrts.lib 
Description The fabs function returns the absolute value of a floating-point number, «x. 
Example double x, y- 


TiO 1) 
fabs (x) ; /* return value = +57.5 */ 


Xx 
Y 
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Syntax 


Defined in 


Description 


Example 
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#include 


double floor (x) 
double x; 


<math.h> 


£loor:..ob7 IN. Fts.1ib 


ereseresesegecegesesecececesecesetecesesecececececesereserelererereresesecetececereces, 


The floor function returns a floating-point number that represents the larg- 
est integer less than or equal to x. 


double 


answer 
answer 


anSwer; 


floor (3.1415); 
floor (-3.5); 


/* answer 
/* answer 


SO 47 
=4...0 *7 


Runtime-Support Functions 


esesatatatetatenereetesis 


Floating-Point Remainder tmod 
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Syntax #include <math.h> 


double fmod(x, y) 
double x, y; 


Defined in fmod.obj in rts.1lib 


Description The fmod function returns the floating-point remainder of x divided by y. If 
y= =0, the function returns 0. 


Example double x, y, UO; 


x = 11.0; 
y 53.08 
r fmod(x, y); /* fmod returns 1.0 */ 
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Syntax 


Defined in 


Description 


Example 
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#include <stdlib.h> 
void free(ptr) 
VOL. *~pers 


memory.cinrts.src 


The free function deallocates memory space (pointed to by ptr) that was 
previously allocated by a malloc, calloc, or realloc call. This makes the 
memory space available again. If you attempt to free unallocated space, the 
function takes no action and returns. For more information, refer to Section 
4.1.4, Dynamic Memory Allocation, on page 4-6. 


This example allocates 10 bytes and then frees them. 


char *x; 
x = malloc(10); /* allocate 10 bytes aif 
free (x); /* free 10 bytes * / 


Runtime-Support Functions 


Syntax 


Defined in 


Description 


Example 


Fraction and Exponent _ frexp 


#include <math.h> 


double frexp(value, exp) 
double value; /* input floating-point number */ 
Tc *exXp; /* pointer to exponent */ 


frexp.obj inrts.lib 


The frexp function breaks a floating-point number into a normalized fraction 
and an integer power of 2. The function returns a value with a magnitude 
in the range (1/2,1) or 0, so that value= = x x 2(**©*P). The frexp function 


stores the power in the int pointed to by exp. If value is 0, both parts of the 
result are 0. 


double fraction; 
int exp; 


fraction = frexp(3.0, &exp); 


/* after execution, fraction is .75 and exp is 2 */ 
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Syntax #include <time.h> 


struct tm *gmtime (timer) 
tame t *timer; 


Defined in gmtime.c in rts.sre 


Description The gmtime function converts a calendar time (pointed to by timer) intoa 
broken-down time, which is expressed as Greenwich Mean Time. 


For more information about the functions and types that the t ime.h header 
declares, refer to Section 5.1.10 on page 5-8. 
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Syntax 


Defined in 


Description 


#include 


isxxx.candctype.cinrts.srce 
Also defined in ctype.h aS macros 


SRS SS 


int 
char c; 
int isalpha (c) 
char c; 
int isascii(c) 
char. -c; 
int iscntrl (c) 
char c; 
int isdigit (c) 
char c; 
int isgraph (c) 
char ¢; 
int islower (c) 
Char <> 
int isprint (c) 
Char; 
int ispunct (c) 
char <c; 
int isspace (c) 
char c; 
int isupper (c) 
char <c; 


int isxdigit (c) 


char c; 


<ctype.h> 


isalnum(c) 


essageeesseeusseeatesenscatessseeasecatecatatotatetetatesetatetotecetetscotetetatstotetetetetotet total esatstanstetenetetateteretscatetanatecetetesatetstonateconscarateteeatstetatetetanssenatscetetstetatetenatetateletetscotecetatscotstecety 


Character 


re 


r 


yping  iSXXX 


These functions test a single argument c to see if it is a particular type of 
character—alphabetic, alohanumeric, numeric, ASCII, etc. If the test is true 
(the character is the type of character that it was tested to be), the function 
returns a nonzero value; if the test is false, the function returns 0. The char- 


acter typing functions include: 
isalnum 


isalpha 
isascii 
iscntrl 
isdigit 
isgraph 


acter for which isalpha or isdigit is true). 


for which islower or isupper is true). 


127). 


identifies numeric characters (‘0’— ‘9’) 


identifies any non-space character. 


identifies alohanumeric ASCII characters (tests for any char- 
identifies alohabetic ASCII characters (tests for any character 


identifies ASCII characters (any character between 0—127). 
identifies control characters (ASCII characters O—31 and 
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islower 


isprint 


ispunct 


isspace 


isupper 
isxdigit 


identifies lowercase alphabetic ASCII characters. 


identifies printable ASCII characters, including spaces (ASCII 
characters 32—126). 


identifies ASCII punctuation characters. 


identifies ASCII spacebar, tab (horizontal or vertical), carriage 
return, formfeed, and newline characters. 


identifies uppercase ASCII alphabetic characters. 


identifies hexadecimal digits (O—9, a—f, A—F). 


The C compiler also supports a set of macros that perform these same func- 
tions. The macros have the same names as the functions, but are prefixed 
with an underscore; for example, _/sascii is the macro equivalent of the 
isascii function. In general, the macros execute more efficiently than the 


functions. 


Runtime-Support Functions 


Multiply by a Power of Two _—Idexp 


Syntax #include <math.h> 


double ldexp(x, exp) 
double x; 
pees exp; 


Definedin idexp.objinrts.1lib 


Description The Idexp function multiplies a floating-point number by a power of 2 and 
returns x x 2®*P. exp can be a negative or a positive value. A range error 
may occur if the result is too large. 


Example double result; 


result = ldexp(1.5, 5); /* result is 48.0 */ 


result = ldexp(6.0, -—3); J*. SPesult as 0 S15: */ 
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Syntax #include <time.h> 
struct tm *localtime (timer) 
ctime-t timer; 
Definedin localtime.cinrts.sre 
Description The local time function converts a calendar time (pointed to by timer) into 


a broken-down time, which is expressed as local time. The function returns 
a pointer to the converted time. 


For more information about the functions and types that the time .h header 
declares, refer to Section 5.1.10 on page 5-8. 
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Defined in 


Description 


Description 


Natural Logarithm log 
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#tinclude <math.h> 


double log (x) 
double x; 


log.obj in rts.lib 


The log function returns the natural logarithm of a real number, x. Adomain 
error occurs if x is negative; a range error occurs if x is 0. 


Eloet x) ‘V3 


ZeILC 2625 
log (x) ; /* Return value = 1.0 */ 


x 
Y 
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Syntax #include <math.h> 


double logl10 (x) 
double x; 


Definedin log.objinrts.lib 


Description The logi0 function returns the base-10 logarithm of a real number, x. A 
domain error occurs if x is negative; a range error occurs if x is 0. 


Example float x, y; 


L005 
log (x) ; /* Return value = 1.0 */ 


Xx 
Y 
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Syntax #include <stdlib.h> 


int ltoa(n, buffer) 
leng- ne /* number to convert ay 
char *buffer; /* buffer to put result in * / 


Defined in jltoa.cinrts.src 


Description The ltoa function converts a long integer to the equivalent ASCII string. If 
the input number n is negative, a leading minus sign is output. The ltoa 
function returns the number of characters placed in the buffer. 


9-51 


ratetater 
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Defined in 


Description 
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esereseTesecetezecereeserete fer ere%s: 


#include <stdlib.h> 


void *malloc (size) 
size t size; /* size of block in bytes */ 


memory.cinrts.sre 


The malloc function allocates space for an object of size bytes and returns 
a pointer to the space. If malloc cannot allocate the packet (that is, if it runs 
out of memory), it returns a null pointer (0). This function does not modify 
the memory it allocates. 


The memory that malloc uses is in a special memory pool or heap. An as- 
sembly language module called sysmem.asm defines this memory pool as 
uninitialized named section called .sysmem. The constant — —_sys- 
MEM SIZE defines the size of the heap as 2048 words. If necessary, you can 
change the size of the heap by changing the valueof | sysmEM sizEand 
reassembling sysmem. asm. For more information, refer to Section 4.1.4, Dy- 
namic Memory Allocation, on page 4-6. 


Runtime-Support Functions 


Syntax 


Defined in 


Description 


etatesatetoteterstotetatscanetecelsretecesetetonerscesscenscetenesonetenarscarssatsteretonstetscetstatetatetstecsteretesatetatetatenstetssessteteceteteretesscatscerstatetatenstenstenstet RS SSRI RISERS SREOSN SRS ROR SORES 


#include <string.h> 
void *memchr(s, c, n) 

void *S; 

char CG; 

Size t n; 
memchr.cinrts.sre 


The memchr function finds the first occurrence of c in the first n characters 
of the object that s points to. If the character is found, memchr returns a 
pointer to the located character; otherwise, it returns a null pointer (0). 


The memchr function is similar to strchr, except the object that memchr 
searches can contain values of 0, and c can be 0. 
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Syntax #include <string.h> 


int memcemp(sl, s2, n) 
void RS 15 *S7 s 
size t n; 


Definedin§ = memcmp.cinrts.sre 


Description The memcmp function compares the first n characters of the object that s2 


points to with the object that si points to. The function returns one of the 
following values: 


< Oif *s1 islessthan *s2. 
Oif *s1 is equalto *s2. 
> Oif *si is greater than *s2. 


The memcmp function is similar to strncmp, except the objects that 
memcmp compares can contain values of 0. 
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Defined in 


Description 


Finclude: <string.h> 


void *memcpy(sl1, s2, n) 
void Asi 5. *S2° 
Sa 7e 20 ny 


memmov.cinrts.sre 


The memcpy function copies n characters from the object that s2 points to 
into the object that s1 points to. /f you attempt to copy characters of overlap- 
ping objects, the function’s behavior is undefined. The function returns the 
value of si. 


The memcpy function is similar to strncpy, except the objects that memcpy 
copies can contain values of 0. 
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Syntax #include <string.h> 


void *memmove(sl, s2, n) 
void WSs. SZ s 
size t n; 


Defined in = memmov.cinrts.sre 
Description The memmove function moves n characters from the object that s2 points 
to into the object that s1 points to; the function returns the value of si. The 


memmove function correctly copies characters between overlapping 
objects. 
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Syntax #include <string.h> 


void *memset(s, c, n) 
void *S; 
char Cc; 
size t n; 


Definedin memset.cinrts.src 


Description The memset function copies the value of c into the first n characters of the 
object that s points to. The function returns the value of s. 
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Syntax #include <stdlib.h> 
void minit() 
Definedin = = memory.cinrts.sre 


Description The minitfunction resets all the space that was previously allocated by calls 
to the malloc, calloc, or realloc functions. 


Ce ee eT Ga tng, Se ae ee ee eye eee ee ee eee ee ee ee 


Note: 


Calling the minit function makes all the memory space in the heap available 
again. Any objects that you allocated previously will be lost; don’t try 
to access them. 


nn Terran SE EE ee | 


The memory that minit uses is in a special memory pool or heap. An assem- 
bly language module called sysmem. asmdefines this memory pool as unini- 
tialized named section called .sysmem. The constant __ SYSMEM_ SIZE de- 
fines the size of the heap as 2048 words. If necessary, you can change the 
size of the heap by changing the value of | _sysmeEmM s1zE and reassem- 
bling sysmem.asm. For more information, refer to Section 4.1.4, Dynamic 
Memory Allocation, on page 4-6. 
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Defined in 


Description 


Example 
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Convert to Calender Time _mktime 


SSR ARN eee te sesetese esate teseeaeeseateteseeees ecetatatedetotatetatereseretesatesecetsteceseteeenssecensesessosnsssens 


#include <time.h> 


time t *mktime (timeptr) 
struct tm *timeptr; 


mktime.cin rts.src 


The mktime function converts a broken-down time, expressed as local time, 
into proper calendar time. The timeptr argument points to a structure that 
holds the broken-down time. 


The function ignores the original values of tm_wday andtm_yday and does 
not restrict the other values in the structure. After successful completion of 
time conversions, tm wdayandtm_yday are set appropriately, and the other 
components in the structure have values within the restricted ranges. The 
final value of tm_mday is not sent until tm_mon andtm_year are determined. 


The return value is encoded as a value of type time_t. If the calendar time 
cannot be represented, the function returns the value —1. 


This example determines the day of the week that July 4, 2001, falls on. 


#include <time.h> 

static const char *const wday[] = { 
“Sunday”, “Monday”, “Tuesday”, “Wednesday”, 
’Thursday» “Eriday”,-"Sarurday”: 37 


struct tm time str; 


tame str-tm year = 2001 =) 1900; 
time str.tm_mon = 
time str.tm mday = 
time str.tm_hour = 
time str.tm min = 
time str.tm sec 
time str.tm_isdst = 


i 
e “Ne “Seo “eo 


rProOo & ~~] 


"ee 


“e 


mktime (&time str); 
printf (“result is %s\n”, wday[time_str.tm_wday]); 


/* After calling this function, time_str.tm_wday 
contains the day of the week for July 4, 2001 */ 


For more information about the functions and types that the t ime. h header 
declares, refer to Section 5.1.10 on page 5-8. 
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Syntax 


Defined in 


Description 


Example 
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#include <math.h> 


double modf(value, iptr) 
double value; 
int *L per: 


modf.obj in rts.1lib 


The modf function breaks a value into a signed integer and a signed frac- 
tion. Each of the two parts has the same sign as the input argument. The 
function returns the fractional part of value and stores the integer as a 
double at the object pointed to by iptr. 


double value, ipart, fpart; 


Value = “344157 
fpart = modf(value, &ipart) ; 


(* BECEr Execution; ipart’ contains: =3.0; e/- 
/* and fpart contains —0.1415. x / 
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Syntax 


Defined in 


Description 


Move Memory movmem 


oseseeeatiaeseceneazseneceseaesscessassesessoenesetecesresassserssacarasoraresssnnaseroneseteten 


#include <stdlib.h> 


char *movmem(src, dest, count) 
char *src ; /* source address sf 
char *dest; /* destination address ag 
char count; /* number of bytes to move x 


movmem.cinrts.src 


The movmem function moves count bytes of memory from the object that 
src points to into the object that dest points to. The source and destination 
areas can be overlapping. 
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POW § Raise to a Power 


Syntax 


Defined in 


Description 


Example 
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#tinclude <math.h> 


double pow(x, y) 
double x, y; /* Raise x to power y */ 


pow.obj inrts.lib 


The pow function returns x raised to the power y. A domain error occurs if 


x = Oandy <0, orif x is negative and y is not an integer. A range error 
may occur. 


double x, y, 2; 


200; 
SF 
pow(x, y); /* return value = 8.0 */ 


x 
_ 
x 


Runtime-Support Functions 


Syntax 


Defined in 


Description 


Array Sort qsort 


so esesecezezesseececececeseseseseceseserecerezefezerelorececenes 


#tinclude <stdlib.h> 


void qsort (base, nmemb, size, compar) 


void *base; 
size t nmemb, size; 
Int (*compar) (); 


gsort.cinrts.sre 


The qsort function sorts an array of nmemb members. Argument base points 
to the first member of the unsorted array; argument size specifies the size 
of each member. 


This function sorts the array in ascending order. 


Argument compar points to a function that compares key to the array 
elements. The comparison function should be declared as: 


int omp(ptril, ptr2) 
void *ptrl, *ptr2; 


The cmp function compares the objects that ptr1 and pt r2 point to and re- 
turns one of the following values: 


< 0 if *ptri isless than *ptr2. 
0 if *ptri is equalto *ptr2. 
> O if *ptri is greater than *ptr2. 
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Defined in 


Description 
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rand/srand Random integer 
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#include <stdlib.h> 


int rand( ) 


void srand (seed) 
unsigned int seed; 


rand.cinrts.sre 


Two functions work together to provide pseudo-random sequence 
generation: 


La The rand function returns pseudo-random integers in the range 
0-RAND_MAX. 


L4 The srand function sets the value of seed so that a subsequent call to 
the rand function produces a new sequence of pseudo-random num- 
bers. The srand function does not return a value. 


If you call rand before calling srand, rand generates the same sequence it 
would produce if you first called srand with a seed value of 1. If you call srand 
with the same seed value, rand generates the same sequence of numbers. 


Runtime-Support Functions 


Syntax 


Defined in 


Description 


Change Heap Size reallo 
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#include <stdlib.h> 

void *realloc(ptr, size) 
void “PLL? /* pointer to object to change af 
Size t size; /* new size (in bytes) of packet mY: 


memory.cinrts.sre 


The realloc function changes the size of the allocated memory pointed to 
by ptr, to the size specified in bytes by size. The contents of the memory 
space (up to the lesser of the old and new sizes) is not changed. 


C4 If ptr is 0, then realloc behaves like malloc. 


La lf ptr points to unallocated space, the function takes no action and 
returns. 


La If the space cannot be allocated, the original memory space is not 
changed and realloc returns 0. 


La lf size=0 and ptr is not null, then realloc frees the space that ptr 
points to. 


If, in order to allocate more space, the entire object must be moved, realloc 
returns a pointer to the new space. Any memory freed by this operation Is 
deallocated. If an error occurs, the function returns a null pointer (0). 


The memory that realloc uses is in a special memory pool or heap. An as- 
sembly language module called sysmem. asm defines this memory pool as 
uninitialized named section called .sysmem. The constant — _sys- 
MEM S1zE defines the size of the heap as 2048 words. If necessary, you can 
change the size ofthe heap by changingthevalueof _ sysm=m stzE and 
reassembling sysmem. asm. Formore information, refer to Section 4.1.4, Dy- 


namic Memory Allocation, on page 4-6. 
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Syntax #include <math.h> 


double sin (x) 
double x; 


Definedin  sin.objinxrts.lib 


Description The sin function returns the sine of a floating-point number, x. x is an angle 
expressed in radians. An argument with a large magnitude may produce a 
result with little or no significance. 


Example double radian, sval; /* sval is returned by sin */ 


radian = 3.1415927; 
sval = sin(radian) ; /* -1 is returned by sin * / 
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Hyperbolic Sine — sinh 
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Syntax #include <math.h> 


double sinh (x) 
double x; 


Definedin  sinh.objinrts.lib 


Description The sinh function returns the hyperbolic sine of a floating-point number, x. 
A range error occurs if the magnitude of the argument is too large. 


Example double x, y; 


x = 0.0; 
y = sinh(x); /* return value = 0.0 */ 
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Syntax 


Defined in 


Description 


Example 
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#include <math.h> 


double sqrt (x) 
double x; 


Sqrt.i0b) Inris.1ab 


The sart function returns the nonnegative square root of a real number x. 
A domain error occurs if the argument is negative. 


double x, y; 


li 


LOO20¢ 
sqrt (x) ; /* return value = 10.0 */ 


x 
Y 


Runtime-Support Functions 


Concatenate Strings strcat 
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Syntax #include <string.h> 


char *strceat(sl, s2) 
char *sl, *s2; 


Defined in strcat.cinrts.sre 


Description The strcat function appends a copy of s2 (including a terminating null char- 
acter) to the end of s1. The initial character of s2 overwrites the null charac- 
ter that originally terminated s1. The function returns the value of s1. 
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strchr = Find First Occurrence of Character 
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Syntax 


Defined in 


Description 
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#include <string.h> 


char *strchr(s, c) 
char *s; 
char c; 


strchr.cinrts.sre 


a tetetetetetetatetefetetatetetetetececenscecececetecsereccecesetaroetetetececetecetscetotesscenonseocecstes stococenerenscerenerecesscosstacenetenevereresereretstatererere sey 


The strchr function finds the first occurrence of c in s. If strchr finds the char- 
acter, it returns a pointer to the character; otherwise, it returns a null pointer 


(0). 


Runtime-Support Functions 


Syntax 


Defined in 


Description 


String Compare —- Strcmp/strcol 


#include <string.h> 
int strcoll(sl, s2) 
char *sl, *s2; 
int stremp(sl, s2) 


char *sl, *s2; 


stremp.cinrts.sre 


atatatanesecatetatetatatetatecetanscetecetatetateenetetets 


The strcmp and strcoll functions compare s2 with si. The functions are 
equivalent; both functions are supported to provide compatibility with ANSI 


C. 
The functions return one of the following values: 


< Qif *si islessthan *s2. 
Oif *si is equalto *s2. 
> Oif *si is greaterthan *s2. 
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Syntax #include <string.h> 


char *strcpy(sl, s2) 
char *sl, *s2; 


Definedin strcpy.cinrts.sre 


Description The strcpy function copies s2 (including a terminating null character) into 
si. If you attempt to copy strings that overlap, the function’s behavior is 
undefined. The function returns a pointer to s1. 
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Syntax #include <string.h> 


size t strespn(sl, s2) 
char *sl, *s2; 


Definedin§  strcspn.cinrts.sre 


Description The strcspn function returns the length of the initial segment of s1, which 
is entirely made up of characters that are not in s2. If the first character in 


s1 Is in s2, the function returns 0. 
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strerror String Error 
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Syntax #include <string.h> 


char *strerror (errnum) 
int errnum; 


Defined in = strerror.cinrts.sre 


Description The strerror function returns the string “function error”. This function 
is supplied to provide ANSI compatibility. 
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Defined in 


Description 
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#include <time.h> 


size t *strftime(s, maxsize, format, timeptr) 


char *s, *format; 
size t maxsize; 
struct tm *timeptr; 


strftime.cinrts.sre 


The stritime function formats a time (pointed to by timeptr) according to 
a format String, and returns the formatted time inthe string s. Upto maxsize 
characters can be written to s. The format parameter is a string of charac- 
ters that tells the strftime function how to format the time; the following list 
shows the valid characters and describes what each character expands to. 


Character is replaced by ... 


%a 
%A 
%b 
%B 
%C 
%d 
%H 
Yl 
Yj 
%mM 
%M 
ep 
%S 
%U 


%X 
%X 
ey 
%Y 
%L 


the abbreviated weekday name (Mon, Tue, ... ) 

the full weekday name 

the abbreviated month name (Jan, Feb, ... ) 

the locale’s full month name 

the date and time representation 

the day of the month as a decimal number (O—31) 

the hour (24-hour clock) as a decimal number (00—23) 

the hour (12-hour clock) as a decimal number (01—12) 

the day of the year as a decimal number (001—366) 

the month as a decimal number (01—12) 

the minute as a decimal number (O0O—59) 

the locale’s equivalent of either AM or PM 

the second as a decimal number (O0O—50) 

the week number of the year (Sunday is the first day of the week) asa 
decimal number (00—52) 

the date representation 

the time representation 

the year without century as a decimal number (00—99) 

the year with century as a decimal number 

the time zone name, or by no characters if no time zone exists 


For more information about the functions and types that the time.h header 
declares, refer to Section 5.1.10 on page 5-8. 
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strlen Find String Length 


Syntax #include <string.h> 


size t strlen(s) 
char Tse 


Definedin§ strlen.cinrts.sre 


Description The strlen function returns the length of s. In C, a character string is termi- 
nated by the first byte with a value of 0 (a null character). The returned result 
does not include the terminating null character. 
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Concatenate Strings strncat 


Syntax #include <string.h> 


char *strncat(sl, s2, n) 
chaz *sl, *s2; 
Size t= n; 


Definedin = strncat.cinrts.sre 


Description The strncat function appends up to n characters of s2 (including a terminat- 
ing null character) to the end of s1. The initial character of s2 overwrites the 
null character that originally terminated s1; strncat appends a null character 
to result. The function returns the value of s1. 
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strncmp Compare Strings 


Syntax #include <string.h> 


int strncmp(sl, s2, n) 
| char *sl, *s2; 
S1ze t n; 


Definedin  strncmp.cinrts.sre 


Description The strncmp function compares up to n characters of s2 with s1. The 
function returns one of the following values: 


< QOif «si islessthan *s2. 
0 if *si is equalto *s2. 
> Oif *s1 is greaterthan *s2. 
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String Copy strncpy 


Syntax #include <string.h> 


char *strncpy(sl, s2, n) 
char Sle MeBee 
Size tn; 


Definedin = strncpy.cinrts.sre 


Description The strncpy function copies up to n characters from s2 into s1. If s2 is nchar- 
acters long or longer, the null character that terminates s2 is not copied. If 
you attempt to copy characters from overlapping strings, the function’s be- 
havior is undefined. If s2 is shorter than n characters, strncpy appends null 
characters to s1 so that s1 contains n characters. The function returns the 
value of s1. 
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strpbrk = Find Any Matching Character 


Syntax #include <string.h> 


char *strpbrk(sl1, s2) 
char *sl, *s2; 


Definedin§ strpbrk.cinrts.sre 


Description The strpbrk function locates the first occurrence in s1 of anycharacter in s2. 
If strobrk finds a matching character, it returns a pointer to that character; 
otherwise, it returns a null pointer (0). 
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Defined in 


Description 


esacesaeaseteretecatetetetetecenete! 


Find Last Occurrence of Character strrchr 


#include <string.h> 


char *strrchr(s ,c) 
char *s; 
004 an oS 


strrchr.cinrts.srce 


The strrchr function finds the last occurrence of c in s. If strrchr finds the 
character, it returns a pointer to the character; otherwise, it returns a null 
pointer (0). 
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strspn = Find Number of Matching Charact 
‘sbebacisoeoseeaesehabeheaeaeasacaeeaecaabneceratecaceracaseeieietzeebebstabebabecseeeeee cheers aceasta eases atacetesetisoresesesesasacesaeesesesatesesesesssssosetesssesesstssssstesssesecesesesesssezesesosesosesesesosntososesesonecoeatoransgonotonosoeenssaroessecocanssonesosapanasocareronscosocosenacosossesesteseerosegosegonecseobecosenssonssonabansonssssnessnssssssssenssessssseeesesesessaesesstieasssssasssesesesesssasenstesssenssersesneesesmeiseseteeessesetanss 


Syntax #include <string.h> 


Size t *strspn(sl, s2) 
Ine ‘S31, *82;3 


Definedin strspn.cinrts.sre 


Description The strspn function returns the length of the initial segment of s1 which is 
entirely made up of characters in s2. If the first character of s1 is notin s2, 
the strspn function returns 0. 
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Defined in 


Description 


PERE EAESESSSTRLereEB teresa see cotecetetecsterecetensteteestesesscosstonesstossresessseassecenssstonsiecesesesensronesotessesenesssocerscesesscessesnossrenesseeceastenssesssscogesscesateessseossssnvasteceseseses OS 


#include <string.h> 
char *strstr(sl, s2) 
char *sl, *s2; 


strstr.cinrts.srce 


The strstr function finds the first occurrence of s2 in s1 (excluding the termi- 
nating null character). If strstr finds the matching string, it returns a pointer 
to the located string; if it doesn’t find the string, it returns a null pointer. If s2 
points to a string with length 0, then strstr returns s1. 
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strtod/strtol/strtoul _Siring to Number 


Syntax 


Defined in 


Description 
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#include <stdlib.h> 
double strtod(nptr, endptr) 


‘Ghar Anpotr; 


char **endptr; 


long int strtol(nptr, endptr, base) 


char *nptr; 
char “**endptr; 
int base; 


unsigned long int strtoul(nptr, endptr, base) 


char *nptr; 
char **endptr; 
Ine base; 


strtod.cinrts.sre 


strtol.cinxrts.sre 


strtoul.cinrts.sre 


Three functions convert ASCII strings to numeric values. For each function, 
argument nptr points to the original string. Argument endptr points to a 
pointer; the functions set this pointer to point to the first character after the 
converted string. The functions that convert to integers also have a third ar- 
gument, base. 


Cd 


Cs 


The strtod function converts a string to a floating-point value. The string 
must have the following format: 

[space] [sign] digits [.digits] [e/E [sign] integer] 

The function returns the converted string; if the original string is empty or 
does not have the correct format, the function returns a 0. If the con- 
verted string would cause an overflow, the function returns 
+HUGE_VAL; if the converted string would cause an underflow, the 
function returns 0. If the converted string causes an overflow or an un- 
derflow, errno is set to the value of ERANGE. 

The strtol function converts a string to a long integer. The string must 
have the following format: 

[space] [sign] digits [.digits] [e/E [sign] integer] 

The strtoul function converts a string to an unsigned long integer. The 
string must be specified in the following format: 

[space] [sign] digits [.digits] [e/E [sign] integer] 


The space is indicated by a spacebar, horizontal or vertical tab, carriage re- 
turn, form feed, or newline. Following the space is an optional sign, and then 
digits that represent the integer portion of the number. The fractional part 
of the number follows, then the exponent, including an optional sign. 


The first unrecognized character terminates the string. The pointer that 
endptr points to is set to point to this character. 
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asheisetuengeustsiseneens 


Syntax #include <string.h> 


char *strtok(sl, s2) 
char *sl, *s2; 


Defined in = strtok.cinrts.srce 


Description Successive calls to the strtok function break si into a series of tokens, each 
delimited by a character from s2. Each call returns a pointer to the next 
token. 
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Syntax #include <math.h> 


double tan (x) 
double x; 


Definedin§ tan.objinxrts.lib 


Description The tan function returns the tangent of a floating-point number, x. x is an 
angle expressed in radians. An argument with a large magnitude may 
produce a result with little or no significance. 


Example double x, y; 


3.1415927/4.0; 
tan (x) ; /* return value = 1.0 */ 


x 


Y 
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Hyperbolic Tangent tanh 
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Syntax #include <math.h> 


double tanh (x) 
double x; 


Definedin§ tanh.objinrts.lib 


Description The tanh function returns the hyperbolic tangent of a floating-point number, 
Xe 


Example double x, y; 


703 
tanh (x) ; /* return value = 0.0 */ 


x 
Y 
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Syntax #include <time.h> 
time t time (timer) 
tame: t “timer; 


Definedin§ time.cinrts.srce 


Description The time function determines the current calendar time, represented in sec- 
onds. If the calendar time is not available, the function returns —1. If timer 
is not a null pointer, the function also assigns the return value to the object 
that timer points to. 


For more information about the functions and types that the time .h header 
declares, refer to Section 5.1.10 on page 5-8. 


Ra RRA ESSERE SES SR REST IE | 
Note: 


The time function is target-system specific, so you must write your own time 
function. 
Oil eminem si miami eee 
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Syntax #include <ctype.h> 


int toascii(c) 
char <c;F 


Definedin§ toascii.cinrts.sre 


Description The toascii function ensures that cis a valid ASCII character by masking the 
lower seven bits. There is also an equivalent macro call_toascii. 
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Syntax #include <ctype.h> 


int tolower(c) 
char oc; 


“int toupper (c) 
char Gc; 


Defined in tolower.cinrts.scr 
toupper.cinrts.sre 


Description Two functions convert the case of a single alphabetic character, c, to upper 
or lower case: 


Li The tolower function converts an uppercase argument to lowercase. 
If c is already in lowercase, tolower returns it unchanged. 


La The toupper function converts a lowercase argument to uppercase. If 
c is already in uppercase, toupper returns it unchanged. 


The functions have macro equivalents named _tolower and _toupper. 
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Syntax 


Description 


Example 


aeselesetelererereresetereterereserererererete’ of 


Variable-Argument Macros/Function Va_arg/va_end/va_start 


#include <stdarg.h> 


type va_arg(ap, type) 

void va_end (ap) 

void va_start(ap, parmN) 

va_list *ap 
Some functions can be called with a varying number of arguments that have 
varying types. Such a function, called a variable-argument function, can use 
the following macros to step through its argumentlist at run time. The ap pa- 
rameter points to an argument in the variable-argument list. 


La The va_start macro initializes ap to point to the first argument in an ar- 
gument list for the variable-argument function. The parmN parameter 
points to the rightmost parameter in the fixed, declared list. 


Lu The va_arg macro returns the value of the next argument in a call toa 
variable-argument function. Each time you call va_arg, itmodifies ap so 
that successive arguments for the variable-argument function can be 
returned by successive calls to va_arg (va_arg modifies ap to point to 
the next argument in the list). The tyoe parameter is a type name; it is 
the type of the current argument in the list. 


La The va_end macro resets the stack environment after va_start and 
va_arg are used. 


Note that you must call va_start to initialize ap before calling va_arg or 
va_end. 


int printf(fmt) /* Has 1 fixed argument and a 


char *fmt /* additional variable arguments */ 


va_list ap; 
va_start(ap, fmt); 


/* Get next arg, an integer ay 
1 = va_arg(ap, int); 

/* Get next arg, a string * / 
S = va_arg(ap, char *); 

/* Get next arg, a long * / 


1 = va_arg(ap, long); 


va_end (ap) /* Reset ny 
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Appendix A 


Error Messages 


Compiler error messages are displayed in the following format, which 
shows the line number in which the error occurs and the text of the message: 


“name.c”’, line n: error message 


These types of errors are not fatal. 


Fatal Error messages 


The errors listed below cause the compiler to abort immediately. 


a 


>> cannot allocate sufficient memory 


The compiler requires a minimum of 512K bytes of memory to run; this 
message indicates that this amount is not available. Supply more dy- 
namic RAM. 


>> can’t open “filename” as source 


The compiler cannot find the file name as entered. Check for spelling 
errors and check to see that the named file actually exists. 


>> can’t open “filename” as intermediate file 


The compiler cannot create the output file. This is usually caused by 
either an error in the syntax of the filename or a full disk. 


>> illegal extension “ext” on output file 
The intermediate file cannot have a “.c” extension. 
>> fatal errors found: no intermediate file produced 


This message is printed after an unsuccessful compilation. Correct the 
errors (other messages will indicate particular errors) and try compila- 
tion again. 


>> cannot recover from earlier errors: aborting 


An error has occurred that prevents the compiler from continuing. 
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E Errors 


Appendix B 


Preprocessor Directives 


The C preprocessor provided with this package is standard and follows Ker- 
nighan and Ritchie exactly. This appendix summarizes the directives that 
the preprocessor supports. Generally, the directives are organized alpha- 
betically, one directive per page; however, related directives (such as 
#if/#else) are presented together on one page. Here’s an alphabetical table 
of contents for the preprocessor directives reference: 


Directive Page 
MOCHIG! ee 5G esG oi ite sto erie arare Supcce cane Gee e Baar aiese B-2 
FESO 3 2 Sis ee he oak tee Sew de ea ee i as he ae eae B-3 
FONG wi d-2:o5-be oe nase eb ets oes oe Rack Ou bn ee B-3 
MG ae echelon ee are ete ene ae eee ae B-3 
POON 1d.ded ces ank Baba Gat ardeaos OS a A. a Ree eS Seas B-3 
PUNGEL. 4.2 e-4e ae oe ot ale eh tea ees Da Bee ee B-3 
PVG ILS ei rce ascended hae eae ee et eae ae ene ieee Bee B-5 
PEWS sas 32 eigen “arse 4 tae feeds oe aces eetan oh clans ee Gye ee ote seagate B-6 
PRUNIOCT sack araeucesassne ara acid a steer ara hid ethce. & God bracers ee Des Bass oe eels B-2 
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#define/#undef Define/Undefine Macros Di 


Syntax 


Description 


Example 


rectives 
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#define namef/(arg,...,arg)] token-string 
#undef name 


The preprocessor supports two directives for defining and undefining 
macros and constants: 


[4 The #define directive assigns a string to a macro. Subsequent 
occurrences of name are replaced by token-string. The name can be 
immediately followed by an argumentiist; the arguments are separated 
by commas, and the list is enclosed in parentheses. Each occurrence 
of an argument is replaced by the corresponding set of tokens from the 
comma-separated string. 


When a macro with arguments is expanded, the arguments are placed 
into the expanded token-string unchanged. After the entire token-string 
is expanded, the preprocessor scans again for names to expand at the 
beginning of the newly created token-string, which allows for nested 
macros. 


Note that there is no space between name and the open parenthesis at 
the beginning of the argumentlist. A trailing semicolon is not required; if 
used, it is treated as part of the token-string. 


La The #undef directive undefines the macro name; that is, it causes the 
preprocessor to forget the definition of name. 


The following example defines the constant £: 
#define f(a,b,c) 3*atb-c 

The following line of code uses the definition of £: 
£(27,begin, minus) 

This line is expanded to: 

3*27+begin-minus 

To undefine £, enter: 

#undef f 


Preprocessor Directives . 
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Description 


raeeteteceetetetefocotecocorscecorocecassenees 


#if constant-expression 

code to compile if condition is true 
[#else 

code to compile if condition is false] 
#endif 


#ifdef name 

code to compile if name is defined 
[#else 

code to compile if name is not defined| 
#endif 


#ifndef name 

code to compile if name is not defined 
[#else 

code to compile if name is defined] 
#endif 


setecetere: 


OOO? 


The C preprocessor supports five conditional processing directives: 


Lk Three directives can begin a conditional block: 


The #if directive tests an expression. The code following an #if 
directive (up to an #else or an #endif) is compiled if the constant-ex- 
pressionevaluates to anonzero value. All binary non-assignment C 
operators, the ?: operator, the unary —, !, and % operators are legal 
in constant-expression. The precedence of the operators is the 
same as in the definition of the C language. The preprocessor also 
supports a unary operator named defined, which can be used in 
constant-expression in one of two forms: 


1) defined(name) or 


2) defined name 


This allows the the utility of #ifdef and #ifndef in an #if directive. Only 
these operators, integer constants, and names which are known by 
the preprocessor should be used in constant-expression. I|n 
particular, the sizeof operator should not be used. 


The #ifdef directive tests to see if name is a defined constant. The 
code following an #ifdef directive (up to an #else or an #endif) is 
compiled if name is defined (by the #define directive) and it has not 
been undefined by the #undef directive. 
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H The #ifndef directive tests to see if name is nota defined constant. 
The code following an #ifndef directive (up to an #else or an #endif) 
is compiled if name is not defined (by the #define directive) or if it 
was undefined by the #undef directive. 


La The #else directive begins an alternate block of code that is compiled 
if: 


m The condition tested by #if is false. 
The name tested by #ifdef is not defined. 


The name tested by #ifndef is defined. 


Note that the #else portion of a conditional block is optional; if the #if, 
#ifdef, or #ifndef test is not successful, then the preprocessor continues 
with the code following the #endif. 


Li The #endif directive ends a conditional block. Each #if, #ifdef, and 
#ifndef directive must have a matching #endif. Conditional compilation 
sequences can be nested. 
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Syntax 


Description 


Include Code 


eedetacetetetocetaretetateteretatetesersteteretatetatetetetetetetetatecsteetstetosenetecetosetntecensns Sieg ices tars 


#include ‘filename’”’ 
or 
#include </filename> 


The #include directive tells the preprocessor to read source statements 
from another file. The preprocessor includes (at the point in the code where 
#include is encountered) the contents of the filename, which are then pro- 
cessed. You can enclose the filename in double quotes or in angle brackets. 


The filename can be acomplete pathname or a filename with no path infor- 
mation. 


La If you provide path information for filename, the preprocessor uses that 
path and does not look for the file in any other directories. 


La If you do not provide path information and you enclose the filename in 
double quotes, the preprocessor searches for the file in: 


1) The directory that contains the current source file. (The current 
source file refers to the file that is being processed when the prepro- 
cessor encounters the #include directive.) 

2) Any directories named with the —i preprocessor option. 

3) Any directories named with the C_DIR environment variable. 


La lf you do not provide path information and you enclose the filename in 
angle brackets, the preprocessor searches for the file in: 


1) Any directories named with the —i preprocessor option. 
2) Any directories named with the C_DIR environment variable. 


[te ee a a ee ee eee ee ee ee ee eee ee ne ee eae aD, 


Note: 


If you enclose the filename in angle brackets, the preprocessor does not 
search for the file in the current directory. 
a a ee eee 
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Syntax #line integer-constant [’filename”] 


Description The #line directive generates line control information for the next pass of the 
compiler. The integer-constant is the line number of the next line, and the 
filename is the file where that line exists. If you do not provide a filename, 
the current filename (specified by the last #line directive) is unchanged. 


This directive effectively sets the =LINE and FILE _ symbols. 
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Appendix C 


Increasing Code 
Generation Efficiency 


The efficiency of the code generated by the TMS320C30 C compiler 
depends largely on how effectively you take advantage of the C compiler op- 
timizations. The following list describes the key constructs that can vastly 
improve the compiler’s effectiveness. 


L§ Use register variables for often-used variables. This is particularly im- 
portant for pointer variables (the compiler allocates four registers for 
pointer register variables). For example, the following code fragment 
exchanges one memory object with another: 


do 

{ 
temp = *++src; 
Asrce = *++dest; 
*dest = temp; 

} 

while (--—n) 


Without register variables, this code takes 12 instructions and 19n 
cycles. With register variables, this code takes only 4 instructions and 
7ncycles. 


L4 Avoid integer multiplies (or use the —m option). The TMS320C30 
MPY1 instruction uses 24-bit operands, forcing the compiler to use run- 
time support to do full 32-bit arithmetic. You can use the —m option, 
which forces the compiler to use MP YI, if you know 24-bit multiplies are 
sufficient for your application. 


[4 Pre-compute subexpressions, especially array references in loops. 
Assign commonly used expressions to register variables where pos- 
sible. | 


Li Use *++ to step through arrays, rather than using an index to recalcu- 
late the address each time through a loop. 
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As an example of pre-computing subexpressions and using *++ to step 
through arrays, consider the following loops: 


main () main () 
{ 
float a[10], b[10]; float. ali) biioty 
LOC. “4:5 Inc. iF 
register float *p=a, 
for (1 = 0; i < 10; ++i) 
ali] = (af{i]j] * 20) + b[il]; for (2: O; 1 < 10; ++1) 
*pO++ (ep 20) se. AGA 


Executes in 19 Cycles Executes in 12 Cycles 


La Use structure assignments to copy blocks of data. The compiler 
generates very efficient code for structure assignments; therefore, nest 
objects within structures and use simple assignments to copy them. 


La Avoid large local frames, and declare the most often used local 
variables first. The compiler uses indirect addressing with an 8-bit off- 
set to access local data. To access objects on the local frame that have 
offsets greater than 255, the compiler must first load the offset into an 
index register resulting ini extra instruction and 2 cycles of pipeline 
delay. 


[4 Avoid the big memory model. The big model is inefficient because the 
compiler reloads the data page pointer (DP) before each access to a 
global or static variable. If you have large array objects, use malloc () 
to dynamically allocate and access the variables via pointers rather than 
declaring them globally. For example: 


int a[1l00000]; int *a= (int *)malloc(100000); / 


ee : /* 11 cycles */ a(il ; /* 5 cycles */ 


Inefficient for Large Array Objects Efficient for Large Array Objects 
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a.out, 2-24 

abort function, 5-18 

abs function, 5-19 

absolute value, 5-19, 5-39 

accessing arguments in a function, 4-16 
accessing local variables in a function, 4-16 
acos function, 5-20 

aliased variables, 2-22 

alignment, 3-6, 4-8 

alternate directories for include files, 2-18 
ANSI C, 1-5, 3-1, 5-71, 5-74 

AR3 register. See FP register 

arc cosine, 5-20 

arc sine, 5-22 

arc tangent, 5-24 

archive library, 2-24 

archiver, 1-3, 2-28 

arguments, 4-15, 4-16 

array, 3-5 

ASCII conversion functions, 5-27 
asctime function, 5-21, 5-34 

asin function, 5-22 

asm statement, 3-11, 4-22, 4-23 


assembler, 1-3 
options 
—al, 2-9 
—ax, 2-9 


assembly language, 4-18 
assembly language interrupt routines, 4-24 
assert function, 5-23 

assert.h header, 5-2, 5-10 

atan function, 5-24 

atan2 function, 5-25 

atexit function, 5-26, 5-37 

atof function, 5-27 

atoi function, 5-27 

atol function, 5-27 
autoincrement addressing, 4-29 


autoinitialization, 2-25 
of constants, 4-30 
of variables, 4-30 
RAM model, 2-26, 4-32 
ROM model, 2-27, 4-33 


base-10 logarithm, 5-50 

big memory model, 1-4, 2-22, 4-3, 4-10, C-2 
bit fields, 4-8 : 
block-repeat registers, 4-14 
boot routine, 4-30 

boot.asm, 4-5 

boot.obj, 2-24—2-25, 2-27 
broken-down time, 5-8, 5-34 
broken-down time function, 5-59 
bsearch function, 5-28 

.Oss section, 4-2—4-7, 4-20 
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( , —S, 2-14 

—z, 2-11 
s 

overview, 2-2 
‘ ’ 
C compiler, 1-3, 1-4 

cl30, 2-3 


C interrupt routines, 4-23 
C language. See TMS320C30 C Language 
—Cc linker option, 2-11, 2-24, 2-27, 4-30 See 
linker options 
~—c option, (CL30), 2-12 
c type.h header, 5-10 
C_DIR environment variable, 2-18, 2-19, B-5 
_c_int00, 2-25, 2-27, 4-23, 4-30 
C_OPTION environment variable, 2-13 
calendar time, 5-8, 5-34, 5-35, 5-59, 5-88 
calling conventions. See function calling con- 
ventions 
calloc function, 4-6, 5-29, 5-42, 5-58 
cc30, 2-21 
ceil function, 5-30 
cg30, 2-22 
character string constants, 4-9 
character typing conversion functions, 5-3, 
5-10 | | 
isalnum, 5-45 
isalpha, 5-45 
isascil, 5-45 
iscntrl, 5-45 
isdigit, 5-45 
isgraph, 5-45 
islower, 5-45 
isprint, 5-45 
ispunct, 5-45 
isspace, 5-45 
isupper, 5-45 
isxdigit, 5-45 
toascii, 5-89 
tolower, 5-90 
toupper, 5-90 
.cinit section, 2-27, 4-2, 4-4, 4-7, 4-19, 4-31, 
4-32 
CL30, 1-3, 1-5, 1-6, 2-3 
options 
—C, 2-12 
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clist, 2-15 
CLK_TCK macro, 5-8, 5-31 
clock function, 5-31 
clock_t type, 5-8 
code generator, 2-16, 2-22—2-28 
options 
—a, 2-22 
—b, 2-22 
—m, 2-22 
—0, 2-23 
—q, 2-23 
-V, 2-23 
—X, 2-23 
—Z, 2-23 
—n, 2-23 
COFF, 1-3, 1-4, 4-2 
compare strings, 5-78 
compiler 
operation, 2-1—2-28 
overview, 2-2 
concatenate strings, 5-69, 5-77 
conditional compilation, 2-17 
conditional processing, B-3 
CONST symbol, 4-10 
constant table, 4-8, 4-10 
constants 
character, 3-2 
enumeration, 3-2 
integer, 3-2 
string, 3-3 
conversion, 5-3 
cos function, 5-32 
cosh function, 5-33 
cosine, 5-32 
cpp30, 2-17 
—cr linker option, 2-24, 2-26, 4-30 See linker 
options 
ctime function, 5-34 
ctype.h header, 5-3 


entry points 
c_intO0O, 2-25 


; for C code, 2-25 
data page pointer register, 4-3 raset vector, 2-25 
data pointer (DP), 4-3, 4-14, 4-30, C-2 


d ond enum, 3-4, 3-7 
cae Section enumeration declarations, 3-7, 3-8 
data size, 1-4 


environment variable. See C_OPTION 
data type storage, 4-8 environment variable (preprocessor), 2-19 
set a 4-8 EPROM programmers, 1-3 
data sizes, 3-4 ERANGE macro, 5-6 


derived, 3-4 errno.h header, 5-6 
equivalent, 3-4 error message macros, 5-10 
name, 3-4 assert, 5-23 
__DATE__, 2-18 error messages, 2-18, 2-21, A-1 
daylight savings time, 5-8 | error reporting, 5-6 
declarations, 3-7 exit, 5-26 
dedicated registers, 4-18 exit function, 5-18, 5-37 
#define preprocessor directive, B-2 exp function, 5-38 
delayed branches, 4-29 exponential function, 5-38 
derived types, 3-4, 3-5 exponential math function, 5-5 


expression analysis, 4-25 


diagnostic information, 5-23 
expressions, 3-6 


diagnostic messages, 5-2 


assert, 5-23 external definitions, 3-7 
NDEBUG macro. See NDEBUG macro external variables, 3-10 
difftime function, 5-35 
div function, 5-36 Fo 


DIV_F function, 4-26, 4-27 


fabs function, 5-39 
DIV_I function, 4-26, 4-27 abs Tunction 


fatal errors messages, A-1 


div_t type, es FILE. _, 2-18 
DIV_U TN GNON er filename specifications, 2-4 
eWision, ee float.h header, 5-3 
DIVU instruction, 4-26 floating-point math functions, 5-5, 5-11 
DP register, 4-14 | acos, 5-20 
dynamic memory allocation, 4-6 asin, 5-22 
atan, 5-24 
E atan2, 5-25 
ceil, 5-30 
EDOM macro, 5-6 ite ae 
ee cosh, 5-33 
#else preprocessor directive, B-3—B-4 exp, 5-38 
emulator, 1-3 fabs, 5-39 


#endif preprocessor directive, B-3—B-4 floor, 5-40 
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fmod, 5-41 
frexp, 5-43 
Idexp, 5-47 
log, 5-49 
log10, 5-50 
modf, 5-60 
pow, 5-62 
sin, 5-66 
sinh, 5-67 
sqrt, 5-68 
tan, 5-86 
tanh, 5-87 
floating-point register variables, 4-13 
floating-point remainder, 5-41 
floor function, 5-40 
fmod function, 5-41 
FP register, 4-5, 4-14, 4-16 
frame pointer, 4-16 
free function, 5-42 
frexp function, 5-43 
function calling conventions 
accessing arguments and local variables, 
4-16 
called function responsibilities, 4-16 
calling function responsibilities, 4-15 
returning structures, 4-17 
saving/restoring registers, 4-16 
stack use, 4-15—4-17 
function structure conventions. See function 
calling conventions 


-g option, 4-29 

general utility functions, 5-7, 5-12 
abort, 5-18 
abs, 5-19 
atexit, 5-26 
atof, 5-27 
atoi, 5-27 
atol, 5-27 
bsearch, 5-28 
calloc, 5-29 
div, 5-36 
exit, 5-37 
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free, 5-42 
labs, 5-19 
Idiv, 5-36 
ltoa, 5-51 
malloc, 5-52 
minit, 5-58 
movmem, 5-61 
qsort, 5-63 
rand, 5-64 
realloc, 5-65 
srand, 5-64 
strtod, 5-84 
Strtol, 5-84 
strtoul, 5-84 
global variables, 3-10, 4-3, 4-30, 4-31 
addressing, 4-8 
reserved space, 4-2 
gmtime function, 5-44 


gregorian time, 5-8 


hardware requirements—PC systems, 1-8 

header files, 5-2—5-8 
assert.h header, 5-2 
ctype.h header, 5-3 
errno.h header, 5-6 
float.h header, 5-3 
limits.h header, 5-3 
math.h header, 5-5 
stdarg.h header, 5-6 
stddef.h header, 5-6 
stdlib.h header, 5-7 
string.h header, 5-7 
time.h header, 5-8 

heap, 4-6, 5-52 

HUGE_VAL, 5-5 

hyperbolic cosine, 5-33 

hyperbolic math function, 5-5 

hyperbolic sine, 5-67 

hyperbolic tangent, 5-87 


—i preprocessor option, 2-18, 2-19, B-5 
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identifiers, 3-2, 4-19 preprocessor, 2-17 
#if preprocessor directive, B-3 isalnum function, 5-45 
#ifdef preprocessor directive, B-3 isalpha function, 5-45 
#include files, 2-17 isascii function, 5-45 
include files, 2-18 iscntrl function, 5-45 
#include preprocessor directive, 5-2 isdigit function, 5-45 
index registers, 4-14, 4-26 isgraph function, 5-45 


islower function, 5-45 
isprint function, 5-45 


initialization, 4-30 
initialization tables, 4-31 


format, 4-31 | ispunct function, 5-45 
initialized sections, 4-2 | isspace function, 5-45 
inline assembly construct (asm), 3-11 isupper function, 5-45 
installation isxdigit function, 5-45 
Macintosh, 1-10 isxxx function, 5-3, 5-45 
PCs, 1-8 
VAX/Ultrix, 1-9 | 
VAX/VMS, 1-9 
workstations with UNIX, 1-9 Kernighan and Ritchie, 1-4, 2-18, 3-1 


preprocessor, 2-17 

The C Programming Language, iv, 1-1 
keywords, 3-2 
Kochan, S., Programming in C, iv 


integer division, 5-36 

integer multiplies, C-1 

integer register variables, 4-13 

interfacing C with assembly language, 4-18 
asm statement, 4-22 
assembly language modules, 4-18 | 
defining variables, 4-20 
inline assembly language, 4-22 
modifying compiler output, 4-22 

interlist utility, 1-3, 1-5, 1-7, 2-1, 2-14, 2-15 

intermediate file, 2-21 


lexical les, 3-10 
interrupt handling, 4-23 errr 


limits 
ale language interrupt routines, fioslingepointiypes: 5S 


integer types, 5-3 


labs function, 5-19 
Idexp function, 5-47 
Idiv function, 5-36 
Idiv_t type, 5-7 


interrupt routines, 4-23 


saving registers, 4-23 limits.h header, 5-3 
interrupt routines, 4-18, 4-23 line number directives, 2-17 
inverse tangent of y/x, 5-25 ——-INE__, 2-18 
invoking the linker, 1-3, 2-11—2-12, 2-28, 4-2 


options, 2-10 
—C, 2-12, 2-27 
—Cr, 2-12, 2-27 


C compiler, 2-3 
CL30 program, 2-3 
code generator, 2-22 


interlist utility, 2-14 linker command file, 2-25 
linker, 2-11, 2-18 linking, 4-4 
parser, 2-21 linking C code, 2-24 
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Ink30, 2-24, 2-26 

loader, 4-11, 4-32 

local frame, 4-16 

local variables, 4-16 
localtime, 5-8, 5-34 
localtime function, 5-48, 5-59 
log function, 5-49 

logi0 function, 5-50 

long immediate values, 4-8 
loop rotation, 4-29 

ltoa function, 5-51 


Macintosh installation, 1-10 
macro, B-2 

macro definitions, 2-17 
main function, 4-30 


malloc function, 4-6, 5-42, 5-52, 5-58, C-2 


map file, 2-25 
math routines, 4-26—4-27 
math.h header, 5-5, 5-11 
member names, 3-8 
memchr function, 5-53 
memcemp function, 5-54 
memcpy function, 5-55 
memmove function, 5-56 
MEMORY linker directive, 2-24 
memory management functions 

calloc, 5-29 

free, 5-42 

malloc, 5-52 

minit, 5-58 

movmem, 5-61 

realloc, 5-65 
memory model, 4-2 

big memory model, 4-3 

dynamic memory allocation, 4-6 

RAM model, 4-7 

ROM model, 4-7 

sections, 4-2 

small memory model, 4-3 
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stack, 4-5 
memory pool, 5-52 
memset function, 5-57 
minit function, 5-58 
mktime function, 5-59 
—mn option, 4-29 
MOD_| function, 4-26, 4-27 
MOD_U function, 4-27 
modf function, 5-60 
MODU instruction, 4-26 
movmem function, 5-61 
MPY_| function, 4-27 
MPYI instruction, 4-26 
multiplication, 4-26 


natural logarithm, 5-49 
NDEBUG macro, 5-2, 5-23 
normal optimization, 2-23 
NULL macro, 5-6 


object alignment, 3-6 
object format converter, 1-3 
object libraries, 2-24, 2-26 
object representation, 4-8 
addressing global variables, 4-8 
character string constants, 4-9 
constant table, 4-10 
data type storage, 4-8 
long immediate values, 4-8 
offsetof macro, 5-6 
optimization, 1-4, 4-28 
options, 2-6—2-10 
conventions, 2-6 
general 
—C, 2-7 
—f, 2-8 
—9, 2-/ 
—idir, 2-7 
—k, 2-7 
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—n, 2-8 

—q, 2-8 

—4q, 2-8 

—S, 2-8 

—Z, 2-8, 2-11 


parallel instructions, 4-29 
parser, 2-16, 2-21 
PC installation, 1-8 
pointer register variables, 4-13 
pointers, 3-4 
data size, 3-4—3-6 
pow function, 5-62 
power, 5-62 
predefined macro names, 2-18 
preinitialized variables, 4-30 
preprocessor, 2-16, 2-17 
environment variable, 2-19 
options 
—C, 2-17 
—dname[=def], 2-17 
—p, 2-17 
—pc, 2-9 
—PP; 2-9 
—q, 2-17 
—i, 2-19, B-5 
idir, 2-17 


predefined macro names, 2-18 
preprocessor directives, 2-18, B-1 


#ifndef, B-3—B-4 
#define, B-2 
#else, B-3—B-4 
#endif, B-3—B-4 
#if, B-3 
#ifdef, B-3 
#include, B-5 
#undef, B-2 

program termination functions 
abort (exit), 5-18 
atexit, 5-26 

— exit, 5-37 
progress information, 2-5 


progress messages, 2-21 
pseudo-random, 5-64 
ptrdiff_t type, 5-6 


—q option, 2-5, 2-21 
qsort function, 5-63 


RAM model of initialization, 2-26, 4-31, 4-32 
rand function, 5-64 
RAND_MAX macro, 5-7 
realloc function, 4-6, 5-42, 5-58, 5-65 
register conventions, 4-12 

ARS (FP) register, 4-14 

block-repeat registers, 4-14 

DP register, 4-14 

expression analysis registers, 4-12 

FP (AR98) register, 4-14 

list of registers, 4-12 

register variables, 4-13 

return values, 4-13 

SP register, 4-14 
register tracking, 4-28 
register variables, 3-7, 3-11, 4-13, 4-28, C-1 
registers, 4-23, 4-25, 4-26 
related documentation 

Advanced C: Techniques and Applica- 

tions, iv 

Programming in C, iv 

The C Programming Language, iv 
responsibilities of a called function, 4-16 
responsibilities of a calling function, 4-15 
ROM model of initialization, 2-25, 2-27, 4-31, 

4-33 | 
rts.lib, 2-24—2-25, 2-27, 4-4, 4-26, 4-30, 5-1 
rts.src, 4-5, 4-26, 5-1, 5-7 
runtime environment, 4-1—4-34 

calling conventions. See function calling 

conventions 
expression analysis, 4-25 
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function structure. See function calling 
conventions 
interfacing C with assembly language, 
4-18 
assembly language modules, 4-18 
defining variables, 4-20 
inline assembly language, 4-22 
modifying compiler output, 4-22 
interrupt handling, 4-23 
assembly language interrupt routines, 
4-24 
interrupt routines, 4-23 
saving registers, 4-23 
math routines, 4-26—4-27 
memory model, 4-2 
big memory model, 4-3 
dynamic memory allocation, 4-6 
RAM model, 4-7 
ROM model, 4-7 
sections, 4-2 
small memory model, 4-3 
stack, 4-5 | 
object representation, 4-8 
addressing global variables, 4-8 
character string constants, 4-9 
constant table, 4-10 
data type storage, 4-8 
long immediate values, 4-8 
register conventions, 4-12 
expression analysis registers, 4-12 
list of registers, 4-12 
register variables, 4-13 
return values, 4-13 
system initialization, 4-30—4-34 
autoinitializing variables and constants, 
4-30 
initialization table format, 4-31 
RAM model, 4-32 
.ROM model, 4-33 


runtime initialization, 2-24 
runtime model, options 
—ma, 2-9 
—mb, 2-9 
—mm, 2-9 
—mr, 2-9 
—mv, 2-9 
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—mx, 2-9 

runtime support, 2-24 
math routines, 4-26 

runtime support functions, 5-1—5-17 
descriptions, 5-16—5-17 
summary table, 5-9—5-17 


—s CL30 option, 2-14 
saving registers during interrupts, 4-23 
saving/restoring registers, 4-16 
searches, 5-28 
section 
.cinit, 4-2 
Stack, 4-2 
text, 4-2 
.bss, 4-2 
data, 4-3 
ssysmem, 4-3 
sections, .stack, 4-30 
SECTIONS linker directive, 2-24 
short multiply, 2-22 
silicon bugs, 2-23 
simulator, 1-3 
sin function, 5-66 
sine, 5-66 
sinh function, 5-67 
size_t type, 5-6 
sizeof, 3-6 
SLn, 4-9 © 
small memory model, 1-4, 4-3, 4-10, 4-30 
Sobelman and Krekelberg, Advanced C: 
Techniques and Applications, iv 
software development tools, 1-2—1-3 
sorts, 5-63 
SP register, 4-5, 4-14 
SPOX, 1-5 
sqrt function, 5-68 © 
square root, 5-68 
srand function, 5-64 
stack overflow, 4-6 
stack section, 4-2, 4-5—4-6, 4-30 


STACK_SIZE, 4-5—4-6 


static variables, 3-10, 4-30, 4-31 


addressing, 4-8 
reserved space, 4-2 
stdarg.h header, 5-6, 5-12 

stddef.h header, 5-6 
stdlib.h header, 5-7, 5-12 
strcat function, 5-69 
strchr function, 5-70 
strcmp function, 5-71 
strcoll function, 5-71 
strcpy function, 5-72 
strcspn function, 5-73 
strerror function, 5-74 
stritime function, 5-75 
string copy, 5-79 
string functions, 5-7, 5-14 
memchr, 5-53 
mememp, 5-54 
memcpy, 5-55 
memmove, 5-56 
memset, 5-57 
strcat, 5-69 
strchr, 5-70 
strcmp, 5-71 
strcoll, 5-71 
strcpy, 5-72 
strcspn, 5-73 
strerror, 5-74 
strien, 5-76 
strncat, 5-77 
strncmp, 5-78 
strncpy, 5-79 
strpbrk, 5-80 
strrchr, 5-81 
strspn, 5-82 
strstr, 5-83 
strtok, 5-85 
string label, 4-9 
string.h header, 5-7, 5-14 
strlen function, 5-76 
strncat function, 5-77 


strncmp function, 5-78 
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strncpy function, 5-79 
strpbrk function, 5-80 
strrchr function, 5-81 
strspn function, 5-82 
strstr function, 5-83 
strtod function, 5-84 
strtok function, 5-85 
strtol function, 5-84 
strtoul function, 5-84 
structure conventions. See function calling 
conventions 
structures, 3-7, 3-8, 4-17 
STYP_COPY, 4-32 
STYP_CPY flag, 2-27 
symbol and style conventions, v 
symbolic debugging, 2-15, 4-29 
symbolic debugging directives, 2-23 
ssysmem, 4-4 
.sysmem section, 4-3, 4-6 
sysmem.asm, 4-6 
_ __SYSMEM_SIZE, 4-5—4-6, 5-7 
system constants 
CONST, 4-10 
__SYSMEM_SIZE, 4-5 
system initialization, 4-30—4-34 
autoinitializing variables and constants, 
4-30 
boot routine, 4-30 
initialization table format, 4-31 
RAM model, 4-32 
ROM model, 4-33 


system reset, 4-24 
system stack, 4-5 


_ 320030, 2-18 

3-operand instructions, 4-28 
tan function, 5-86 

tangent, 5-86 

tanh function, 5-87 

text section, 4-2, 4-4 

time, 5-21 
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time function, 5-88 tokens, 5-85 

time functions, 5-8, 5-15 tolower function, 5-90 
asctime, 5-21 toupper function, 5-90 
clock, 5-31 trigonometric math function, 5-5 
ctime, 5-34 


difftime, 5-35 
gmtime, 5-44 


localtime, 5-48 #undef preprocessor directive, B-2 


mktime, 5-59 gaint 
strftime, 5-75 uninitialized sections, 4-2 
time, 5-88 union, 3-8 
time.h header, 5-8, 5-15 UNIX workstation installation, 1-9 
__TIME__, 2-18 
time_t type, 5-8 
tm structure, 5-8 va_arg function, 5-91 
tm type. See broken-down time va_end function, 5-91 
TMS320C30 C language, 3-1—3-12 va_start function, 5-91 
See also ANSI C language variable argument functions and macros, 
asm statement, 3-11 5-6, 5-12 
constants, 3-2 va_arg, 5-91 
data types, 3-4—3-5 va_end, 5-91 
declarations, 3-7—3-9 va_start, 5-91 


enum. See enum 
expressions, 3-6 
external definitions, 3-7 
global variables, 3-10 


variable-argument function, 5-91 


variable-argument functions and macros, di- 
rectives. See preprocessor directives 


identifiers, 3-2 VAX/Ultrix installation, 1-9 
keywords, 3-2 VAX/VMS installation, 1-9 
lexical scope rules, 3-10 void, 3-4, 3-6 

object alignment, 3-6 volatile variables, 2-23 


related documentation 
Advanced C: Techniques and Applica- 
tions, iv, 3-1 


Programming in C, iv wildcard, 2-4 
The C Programming Language, iv 
static variables, 3-10 
TMS320C30 target system, 1-3 


toascii function, 5-89 XDS emulator, 1-3 
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NE, Albuquerque, NM 87107, (505) 345-2555. 


NEW YORK: East Syracuse: 6365 Collamer Dr., 
East Syracuse, NY 13057, (315) 463-9291; 
Melville: 1895 Walt Whitman Rd., P.O. Box 2936, 
Melville, NY 11747, (516) 454-6600; 

Pittsford: 2851 Clover St., Pittsford, NY 14534, 
(716) 385-6770; 

Poughkeepsie: 385 South Rd., Poughkeepsie, 

NY 12601, (914) 473-2900. 


NORTH CAROLINA: Charlotte: 8 Woodlawn Green, 
Woodlawn Rd., Charlotte, NC 28210, (704) 
527-0933; Raleigh: 2809 Highwoods Bivd., Suite 100, 
Raleigh, NC 27625, (919) 876-2725. 


OHIO: Beachwood: 23775 Commerce Park Rd., 
Beachwood, OH 44122, (216) 464-6100; 
Beavercreek: 4200 Colonel Glenn Hwy 
Beavercreek, OH 45431, (513) 427- 6200. 


OREGON: Beaverton: 6700 SW 105th St., Suite 110, 
Beaverton, OR 97005, (503) 643-6758. 


PENNSYLVANIA: Blue Bell: 670 Sentry Pkwy, 
Blue Bell, PA 19422, (215) 825-9500. 


PUERTO RICO: Hato Rey: Mercantil Plaza Bidg., 
Suite 505, Hato Rey, PR 00918, (809) 753-8700. 


TENNESSEE: Johnson City: Erwin Hwy, 
P.O. Drawer 1255, Johnson City, TN 37605 
(615) 461-2192. 


TEXAS: Austin: 12501 Research Bivd., Austin, TX 
78759, (512) 250-7655; Richardson: 1001 E. 
Campbell Rd., Richardson, TX 75081, 

(214) 680-5082; Houston: 9100 Southwest Frwy., 
Suite 250, Houston, TX 77074, (713) 778-6592; 
San Antonio: 1000 Central Parkway South, 

San Antonio, TX 78232, (512) 496-1779. 


UTAH: Murray: 5201 South Green St., Suite 200, 
Murray, UT 84123, (801) 266-8972. 


WASHINGTON: Redmond: 5010 148th NE, Bidg B, 
Suite 107, Redmond, WA 98052, (206) 881-3080. 


WISCONSIN: Brookfield: 450 N. Sunny Slope, Suite 
150, Brookfield, WI 53005, (414) 782-2899. 


CANADA: Nepean: 301 Moodie Drive, Mallorn Center, 
Nepean, Ontario, Canada, K2H9C4, 

(613) 726-1970. Richmond HW: 280 Centre St. E., 
Richmond Hill L4C1B81, Ontario, Canada 

(416) 884-9181; St. Laurent: Ville St. Laurent 
Quebec, 9460 Trans Canada Hwy., St. Laurent. 
Quebec, Canada H4S1R7, (514) 336-1860. 


ARGENTINA: Texas instruments Argentina Viamonte 
1119, 1053 Capital Federal, Buenos Aires, Argentina, 
541/748-3699 


AUSTRALIA (& NEW ZEALAND): Texas Instruments 
Australia Ltd.: 6-10 Talavera Rd., North Ryde 
(Sydney), New South Wales, Australia 2113, 

2 + 887-1122; Sth Floor, 418 St. Kilda Road, 
Melbourne, Victoria, Australia 3004, 3 + 267-4677; 
171 Philip Highway, Elizabeth, South Australia 5112, 
8 + 255-2066. 


AUSTRIA: Texas Instruments Ges.m.b.H.: 
Industriestrabe 8/16, A-2345 Brunn/Gebirge, 
2236-846210. 


BELGIUM: Texas Instruments N.V. Beigium S.A.: 
Avenue Jules Bondetlaan 11, 1140 Brussels, en 
(02) 242-3080. 


BRAZIL: Texas Instruments Electronicos do Brasil 
Ltda.: Rua Paes Leme, 524-7 Andar Pinheiros, 05424 
Sao Paulo, Brazil, 0815-6166. 


DENMARK: Texas Instruments ae, Mairelundvej 46E, 
2730 Herlev, Denmark, 2 - 91 74 00. 


FINLAND: Texas Instruments Fintand OY: 
Ahertajantie 3, P.O. Box 81, ESPOO, Finland, (90) 
0-461-422. 


FRANCE: Texas Instruments France: Paris Office, BP 
67 8-10 Avenue Morane-Saulnier, 78141 Velizy- 
Villacoublay cedex (1) 30 70 1003. 


GERMANY (Fed. Republic of Germany): Texas 
Instruments Deutschland GmbH: Haggertystrasse 1, 
8050 Freising, 8161 + 80-4591; Kurfuerstendamm 
195/196, 1000 Berlin 15, 30 + 882- 7365; ill, Hagen 
43/Kibbelstrasse, .19, 4300 Essen, 201- 24250; 
Kirchhorsterstrasse 2, 3000 Hannover 51, 
511+648021; Maybachstrabe 11, 7302 Ostfildern 
2-Nelingen, 711 + 34030. 
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HONG KONG: Texas Instruments Hong Kong Ltd., 8th 
Floor, World Shipping Ctr., 7 Canton Rd., Kowloon, 
Hong Kong, (852) 3-7351223. 


IRELAND: Texas Instruments (Ireland) Limited: 
7/8 Harcourt Street, Stillorgan, County Dublin, Eire, 
1 781677. 


ITALY: Texas Instruments Italia S.p.A. Divisione 
Semiconduttori: Viaie Europa, 40, 20093 Cologne 
Monzese (Milano), (02) 253001; Via Castello della 
Magliana, 38, 00148 Roma, (06) 5222651; 

Via Amendola, 17, 40100 Bologna, (051) 554004. 


JAPAN: Tokyo Marketing/Sales (Headquarters): 
Texas Instruments Japan Ltd., MS Shibaura Bidg., 9F, 
4-13-23 Shibaura, Minato-ku, Tokyo 108, Japan, 
03-769-8700. Texas Instruments Japan Ltd.: Nissho- 
Iwai Bidg. 5F, 30 imabashi 3-chome, Higashi-ku, 
Osaka 541, Japan, 06-294-1881; Daini Toyota West 
Bidg. 7F, 10-27 Meieki 4-chome, Nakamura-ku, 
Nagoya 450, 052-583-8691; Daiichi Seimei Bldg. 6F, 
3-10 Oyama-cho, Kanazawa 920, Ishikawa-ken, 
0762-23-5471; Daiichi Olympic Tachikawa Bldg. 6F, 
1-25-12 Akebono-cho, Tachikawa 190, Tokyo, 
0425-27-6426; Matsumoto Showa Bidg. 6F, 2-11 
Fukashi 1-chome, Matsumoto 390, Nagano-ken, 
0263-33-1060; Yokohama Nishiguchi KN Big 6F, 
2-8-4 Kita-Saiwai-cho, Nishi-ku, Yokohama 220, 
045-322-6741; Nihon Seimei Kyoto Yasaka Bidg. 5F, 
843-2 Higashi Shiokohjidori, Nishinotoh-in Higashi-iru, 
Shiokouji, Shimogyo-ku, Kyoto 600, 075-341-7713; 
2597-1, Aza Harudai, Oaza Yasaka, Kitsuki 873, Oita- 
ken, 09786-3-3211; Miho Plant, 2350 Kihara Miho- 
mura, Inashiki-gun 300-04, Ibaragi-ken, 
0298-85-2541. 


KOREA: Texas Instruments Korea Ltd., 28th FI., Trade 
Tower, #159, Samsung-Dong, Kangnam-ku, Seoul, 
Korea 2 + 551-2810. 


MEXICO: Texas Instruments de Mexico S.A.: Alfonso 
Reyes— 115, Col. Hipodromo Condesa, Mexico, D.F., 
Mexico 06120, 525/525-3860. 


MIDDLE EAST: Texas Instruments: No. 13, 1st Floor 
Mannai Blidg., Diplomatic Area, P.O. Box 26335, 
Manama Bahrain, Arabian Gulf, 973 + 274681. 


NETHERLANDS: Texas instruments Holland B.V., 
19 Hogehilweg, 1100 AZ Amsterdam — Zuidoost, 
Holland 20 + 5602911. 


NORWAY: Texas Instruments Norway A/S: PB106, 
Refstad 0585, Oslo 5, Norway, (2) 155090. 


PEOPLES REPUBLIC OF CHINA: Texas Instruments 
China Inc., Beijing Representative Office, 7-05 Citic 
Bidg., 19 Jianguomenwai Daije, Beijing, China, (861) 
5002255, Ext. 3750. 


PHILIPPINES: Texas Instruments Asia Ltd.: 14th Floor, 
Ba- Lepanto Bidg., Paseo de Roxas, Makati, Metro 
Manila, Philippines, 817-60-31. 


PORTUGAL: Texas Instruments Equipamento 
Electronico (Portugal), Lda.: Rua Eng. Frederico Ulrich, 
2650 Moreira Da Maia, 4470 Maia, Portugal, 
2-948-1003. 


SINGAPORE (+ INDIA, INDONESIA, MALAYSIA, 
THAILAND): Texas instruments Singapore (PTE) Ltd., 
Asia Pacific Division, 101 Thompson Rd. #23-01, 
United Square, Singapore 1130, 350-8100. 


SPAIN: Texas Instruments Espana, S.A.: C/Jose 
Lazaro Galdiano No. 6, Madrid 28036, 1/458.14.58. 


SWEDEN: Texas Instruments International Trade 
Corporation (Sverigefilialen): S-164-93, Stockholm, 
Sweden, 8 - 752-5800 


SWITZERLAND: Texas Instruments, Inc., Reidstrasse 
6, CH-8953 Dietikon (Zuerich) Switzerland, 
1-740 2220. 


TAIWAN: Texas Instruments Supply Co., 9th Floor 
Bank Tower, 205 Tun Hwa N. Rd., Taipei, Taiwan, 
Republic of China, 2 + 713-9311. 


UNITED KINGDOM: Texas Instruments Limited: 
Manton Lane, Bedford, MK41 7PA, England, 0234 
270111. 


TI Sales Offices 


ALABAMA: Huntsville (205) 837-7530. 


| ARIZONA: Phoenix (602) 995-1007; 
Tucson (602) 292-2640. 


CALIFORNIA: Irvine (714) 660-1200; 
Roseville (916) 786-9208; 

San Diego (619) 278-9601; 

Santa Clara (408) 980-9000; 
Torrance (213) 217-7010; 

Wooditand Hilis (818) 704-7759. 


COLORADO: Aurora (303) 368-8000. 
CONNECTICUT: Wallingford (203) 269-0074. 


FLORIDA: Altamonte Springs (305) 260-2116; 
Ft. Lauderdale (305) 973-8502; 
Tampa (813) 885-7411. 


GEORGIA: Norcross (404) 662-7900. 
ILLINOIS: Arlington Heights (312) 640-2925. 


INDIANA: Carmet (317) 573-6400; 
Ft. Wayne (219) 424-5174. 


IOWA: Cedar Raplds (319) 395-9550. 
KANSAS: Overland Park (913) 451-4511. 
MARYLAND: Columbla (301) 964-2003. 
MASSACHUSETTS: Waltham (617) 895-9100. 


MICHIGAN: Farmington Hills (313) 553-1569; 
Grand Rapids (616) 957-4200. 


MINNESOTA: Eden Prairie (612) 828-9300. 
MISSOURI: St. Louls (314) 569-7600. 

NEW JERSEY: Iselin (201) 750-1050. 

NEW MEXICO: Albuquerque (505) 345-2555. 


NEW YORK: East Syracuse (315) 463-9291; 
Melville (516) 454-6 

Pittsford (716) 385-6770; 

Poughkeepsie (914) 473-2900. 


NORTH CAROLINA: Charlotte (704) 527-0933; 
Raleigh (919) 876-2725. 


OHIO: Beachwood (216) 464-6100; 
Beaver Creek (513) 427-6200. 


OREGON: Beaverton (503) 643-6758. 
PENNSYLVANIA: Blue Bell (215) 825-9500. 
PUERTO RICO: Hato Rey (809) 753-8700. 
TENNESSEE: Johnson City (615) 461-2192. 


TEXAS: Austin AE 250-7655; 
Houston (713) 778-6 

Richardson (214) 680 5082: 
San Antonio (512) 496-1779. 


UTAH: Murray (801) 266-8972. 
WASHINGTON: Redmond (206) 881-3080. 
WISCONSIN: Brookfield (414) 782-2899. 


CANADA: pr grab Ontarlo (613) 726-1970; 
Richmond Hill, Ontarlo (416) 884-9181; 
St. Laurent, Quebec (514) 336-1860. 


TI Regional 
Technology Centers 


CALIFORNIA: Irvine (714) 660-8105; 
Santa Clara (408) 748-2220; 


GEORGIA: Norcross (404) 662-7945. 
ILLINOIS Arlington Heights (312) 640-2909. 
MASSACHUSETTS: Waltham (617) 895-9196. 
TEXAS: Richardson (214) 680-5066. 
CANADA: Nepean, Ontario (613) 726-1970. 


TI Distributors 


Ti AUTHORIZED DISTRIBUTORS 
Arrow/Kierulff Electronics Group 
Arrow (Canada) 

Future Electronics (Canada) 
GRS Electronics Co., Inc. 
Hall-Mark Electronics 

Marshall Industries 

Newark Electronics 

Schweber Electronics 

Time Electronics 

Wyle Laboratories 

Zeus Components 


— OBSOLETE PRODUCT ONLY — 
Rochester Electronics, Inc. 
Newburyport, Massachusetts 
(508) 462-9332 


ALABAMA: Arrow/Kierulft (205) 837-6955; 
Hall-Mark (205) 837-8700; Marshall (205) 881-9235; 
Schweber (205) 895-0480. 


ARIZONA: Arrow/Kierulff (602) 437-0750; 
Hall-Mark (602) 437-1200; Marshall (602) 496-0290; 
Schweber (602) 431-0030; Wyle (602) 866-2888. 


CALIFORNIA: Los Angeles/Orange County: 

Arrow/Kierulff (818) 701-7500, (714) 838-5422; 

Hall-Mark (818) 773-4500, (714) 669-4100; 

Marshall (818) 407-0101, (818) 459-5500, 

(714) 458-5395; Schweber (818) 880-9686; 

(714) 863-0200, (213) 320-8090; Wyle (818) 880-9000, 

Bb 863-9953; Zeus (714) 921-9000; (818) 889-3838; 
acramento: Hall-Mark (916) 624-9781; 

Marshall (916) 635-9700; Schweber (916) 364-0222; 

Wyle (916) 638-5282; 

San Diego: Arrow/Kierulft 619) 565-4800; 

Hall-Mark (619) 268-1201; Marshall (619) 578-9600; 

Schweber (619) 450-0454; Wyle (619) 565-9171; 


San Francisco Bay Area: Arrow/Kieruiff (408) 745-6600, 


Hall-Mark (408) 432-0900; Marshall (408) 942-4600; 
Schweber (408) 432-7171; Wyle (408) 727-2500; 


| Zeus (408) 998-5121. 


COLORADO: Arrow/Kierulff (303) 790-4444; 
Hall-Mark (303) 790-1662; Marshall (303) 451-8383; 
Schweber (303) 799-0258; Wyle (303) 457-9953. 


CONNETICUT: Arrow/Kierulff (203) 265-7741; 
Hali-Mark (203) 271-2844; Marshall (203) 265-3822; 
Schweber (203) 264-4700. 


FLORIDA: Ft. Lauderdale: 


Arrow/Kierulff (305) 429-8200; Hall-Mark (305) 971-9280; 


Marshall (305) 977-4880; Schweber (305) 977-7511; 
Orlando: Arrow/Kierulff (407) 323-0252; 

Hall-Mark (407) 830-5855; Marshall (407) 767-8585; 
Schweber (407) 331-7555; Zeus (407) 365-3000; 
Tampa: Hall-Mark (813) 530-4543; 

Marshall (813) 576-1399; Schweber (813) 541-5100. 


GEORGIA: Arrow/Kierulff (404) 449-8252; 
Hall-Mark (404) 447-8000; Marshall (404) 923-5750; 
Schweber (404) 449-9170. 


ILLINOIS: Arrow/Kieruiff (312) 250-0500; 
Hall-Mark (312) 860-3800; Marshall (312) 490-0155; 
Newark (312) 784-5100; Schweber (312) 364-3750. 


INDIANA: Indianapolis: Arrow/Kierulff (317) 243-9353; 
Hall-Mark (317) 872-8875; Marshall (317) 297-0483; 
Schweber (317) 843-1050. 


IOWA: Arrow/Kierulff (319) 395-7230; 
Schweber (319) 373-1417. 


KANSAS: Kansas City: Arrow/Kierulff (913) 541-9542; 


Hall-Mark (913) 888-4747; Marshall (913) 492-3121; 
Schweber (913) 492-2922. 


TEXAS 
INSTRUMENTS 


| MARYLAND: Arrow/Kierulff (301) 995-6002; 


Hall-Mark (301} 988-9800; Marshall (301) 235-9464; 
Schweber (301) 840-5900; Zeus (301) 997-1118. 


MASSACHUSETTS Arrow/Kierulff (508) 658-0900; 
Hall-Mark (508) 667-0902; Marshal! (508) 658-0810; 
Schweber (617) 275-51 00; Time (617) 532-6200; 
Wyle (617) 273-7300; Zeus (617) 863-8800. 


MICHIGAN: Detroit: Arrow/Klerulff (313) 462-2290; 
Hall-Mark 2 3) 462-1205; Marshall (313) 525-5850; 
Newark (313) 967-0600; Schweber ( 13) 525-8100; 
Grand Rapids: Arrow/Klerulff (616) 243-0912. 


MINNESOTA: Arrow/Klerulff (61 4) 830-1800; 
Hall-Mark (612) 941-2600; Marshall (612) 559-2211; 
Schweber (612) 941-5280. 


MISSOURI: St. Louls: Arrow/Kierulff (314) 567-6888; 
Hall-Mark (314) 291-5350; Marshall (314) 291-4650; 
Schweber (314) 739-0526. 


NEW HAMPSHIRE: Arrow/Kierulff (603) 668-6968; 
Schweber (603) 625-2250. 


NEW JERSEY: Arrow/Kierulff (201) 538-0900, 
(609) 596-8000; GRS Electronics (609) 964-8560; 
Hall-Mark (201) 575-4415, (201) 882-9773, 

(609) 235-1900; Marshall ‘(201) 882-0320, 

(609) 234-9190; Schweber (201) 227-7880. 


NEW MEXICO: Arrow/Kierulff (505) 243-4566. 


NEW YORK: Long Island: 

Arrow/Kierulff (516) 231-1009; Hall-Mark (516) 737-0600; 
Marshall (516) 273-2424; Schweber (516) 334-7474; 
Zeus (914) 937-7400; 

Rochester: Arrow/Kierulff 716) 427-0300; 

Hall-Mark (716) 425-3300; Marshall (716) 235-7620; 
Schweber (716) 424-2222: 

Syracuse: Marshall (607) 798-1611. 


NORTH CAROLINA: Arrow/Kierulff (919) 876-3132, 
(919) 725-8711; Hall-Mark (919) 872-0712; 
Marshall (919) 878-9882; Schweber (919) 876-0000. 


OHIO: Cleveland: Arrow/Klerulff (216) 248-3990; 
Hall-Mark (216) Ea Marshall (216) 248-1788; 
Schweber (216) 464-29 

Columbus: Hall-Mark 6 4) 888-331 2. 

Dayton: Arrow/Kierulff (513) 435-5563 

Marshall (513) 898-4480; Schweber (51 3) 439-1800. 


OKLAHOMA: Arrow/Kierulff (918) 252-7537; 
Schweber (918) 622-8003. 


OREGON: Arrow/Kierulff (503) 645-6456; 
Marshall (503) 644-5050; Wyle (503) 640-6000. 


PENNSYLVANIA: Arrow/Kierulff (412) 856-7000, 
(215) 928-1800; GRS Electronics (215) 922-7037; 
Marshall (412) 963-0441; Schweber 2 5) 441 -0600, 
(412) 963-6804. 


TEXAS: Austin: Arrow/Kierulff (512) 835-4180; 
Hall-Mark (512) 258-8848; Marshall (512) 837-1991; 
Schweber (512) 339-0088; Wyle (512) 834-9957; 
Dallas: Arrow/Kieruiff (214) 380-6464; 

Hall-Mark (214) 553-4300; Marshall (214) 233-5200; 
Schweber (214) 661-5010; Wylie (214) 235-9953; 
Zeus (214) 783-7010; 

El Paso: Marshall (915) 593-0706; 

Houston: Arrow/Kierulff (713) 530-4700; 

Hall-Mark (713) 781-6100; Marshall (713) 895-9200; 
Schweber (713) 784-3600; Wyle (713) 879-9953. 


UTAH: Arrow/Kierulff (801) 973-6913; 
Hall-Mark (801) 972-1008; Marshall (801) 485-1551; 
Wyle (801) 974-9953. 


WASHINGTON: Arrow/Kierulff (206) 575-4420; 
Marshall (206) 486-5747; Wyle (206) 881-1150. 


WISCONSIN: Arrow/Kierulff (414) 792-0150; 
Hall-Mark (414) 797-7844; Marshall (414) 797-8400; 
Schweber (414) 784-9020. 


CANADA: Calgary: Future os 235-5325; 
Edmonton: Future (403) 438-2858; 
Montreal: Arrow Canada (51 Fi errs 5511; 
Future (514) 694-7710; 

Ottawa: Arrow Canada (613) 226-6903; 
Future (613) 820-83 

Quebec City: now — (418) 871-7500; 
Toronto: Arrow Canada (416) 672-7769; 


Future (416) 638-4771; Marshall (416) 674-21 61; 


Vancouver: Arrow Canada (604) 291-2986; 
Future (604) 294-1166. 


Customer 
Response Center 


TOLL FREE: (800) 232-3200 


OUTSIDE USA: (214) 995-6611 
(8:00 a.m. — 5:00 p.m. CST) 


w% 
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